Contributing to LocaleDB

LocaleDB is an open-source project and we love contributions from developers worldwide!

Ways to Contribute

1. Fix or Update Country Data

If you notice incorrect locale data for a country:

1. Fork the GitHub repository
2. Edit the country JSON file in /data/countries/
3. Verify your changes against official sources (CLDR, local standards)
4. Submit a Pull Request with a clear description

2. Add a New Country

To add a country not yet in LocaleDB:

1. Use an existing country JSON as a template
2. Create /data/countries/XX.json (XX = ISO alpha-2 code)
3. Fill in all required fields using CLDR data
4. Update /data/_index.json with the new country
5. Submit a Pull Request

3. Improve the Website

Help us make LocaleDB better by:

• Improving UI/UX
• Adding search functionality
• Creating comparison tools
• Writing better documentation
• Fixing bugs

Data Schema

Each country JSON file follows a strict TypeScript schema defined in /src/types/country.ts. Key sections:

• basics - Country name, capital, coordinates, flag
• codes - ISO 3166, BCP47, IOC, FIFA codes
• currency - Symbol, position, separators, patterns
• dateTime - Date/time formats, month/day names, timezones
• numberFormat - Decimal/thousands separators, grouping
• phone - Calling code, format, number lengths
• addressFormat - Postal code format, address line order
• locale - Writing direction, measurement system, paper size

Data Sources to Reference

When adding or updating data, use these authoritative sources:

• CLDR (Unicode Common Locale Data Repository)
• mledoze/countries GitHub Repository
• National standards organizations (e.g., TSE for Turkey, ANSI for USA)
• Official government websites for postal codes and formats

Pull Request Guidelines

• One change per PR - Don't mix data updates with code changes
• Clear commit messages - "Update Turkish currency format" not "fix data"
• Reference sources - Link to CLDR or official documentation
• Test locally - Run pnpm dev and verify changes
• Validate JSON - Ensure proper formatting and schema compliance

Code of Conduct

We're committed to fostering a welcoming community. Be respectful, constructive, and collaborative. Harassment or toxic behavior will not be tolerated.

Questions?

Open a GitHub Discussion if you need help or have questions about contributing.