Add a New Locale

Adding a new locale involves collecting realistic data (names, cities, streets) and formatting rules for a specific country or region. Unlike adding a new resource type, this is primarily a data collection task.

The Locale Checklist

A complete locale implementation requires several files organized into directories representing the locale (e.g., fr_fr), language (e.g., fr), and country (e.g., fr).

Note: All directory and file names use lowercase (e.g., fr_fr, en_us) for cross-platform consistency.

Required Locale Files

Path: typespec/resources/locale/{locale}/ (e.g., locale/fr_fr/)

File	Description	Example
given_male_names.txt	Common male first names	Jean, Pierre, Lucas
given_female_names.txt	Common female first names	Marie, Léa, Camille
family_names.txt	Common surnames	Martin, Bernard, Dubois
cities.txt	Major cities in this region	Paris, Lyon, Marseille
streets.txt	Common street names	Rue de la Paix, Avenue Victor Hugo
zipcodes.txt	Examples of valid postal codes	75001, 69002
name_format.txt	How names are ordered	{given_name} {family_name}

Required Language Files

Path: typespec/resources/lang/{language}/ (e.g., lang/fr/)

File	Description	Example
nouns.txt	Common nouns in this language	livre, table, chaise
adjectives.txt	Common adjectives	beau, grand, petit
verbs.txt	Common verbs	manger, dormir, aller
months.txt	Month names in this language	janvier, février, mars
weekdays.txt	Weekday names in this language	lundi, mardi, mercredi

Required Country Files

Path: typespec/resources/country/{country}/ (e.g., country/fr/)

File	Description	Example
address_format.txt	How addresses are ordered	{street}\n{zip} {city}
street_format.txt	How street numbers/names combine	{number} {street}
phone_number_patterns.txt	Patterns for valid phones	0# ## ## ## ##
timezones.txt	Valid IANA timezone names	Europe/Paris

Step 1: Create Directory Structure

Localized data is organized at three levels depending on how specific the data is:

1. Locale Level (language_country)

Use this for data that varies by both language and country (e.g., en_us vs en_gb). This is where most names and cities belong.

mkdir -p typespec/resources/locale/fr_fr

2. Language Level (language)

Use this for data that is the same for all countries speaking that language (e.g., common nouns, adjectives, months, weekdays).

mkdir -p typespec/resources/lang/fr

3. Country Level (country)

Use this for data that is specific to a country but independent of the language (e.g., phone formats, timezones, address formats).

mkdir -p typespec/resources/country/fr

Note: Use lowercase for all directory names (fr_fr, not fr_FR or FR_fr).

Step 2: Prepare Data Files

Each .txt file must follow these rules:

• Encoding: Must be UTF-8 without BOM.
• Format: One entry per line.
• Cleaning: No empty lines, no leading/trailing whitespace.
• Uniqueness: Avoid duplicate entries within a file.

Example locale/fr_fr/cities.txt:

Paris
Marseille
Lyon
Toulouse
Nice

Step 3: Formatting Placeholders

Some files use placeholders that are replaced during data generation.

Address Format

Used in address_format.txt. Common placeholders:

• {street_address}: The combined street number and name.
• {locality}: Usually the city.
• {region}: State, province, or department.
• {postal_code}: The zip or postal code.
• {country}: The full country name.

Phone Number Patterns

Used in phone_number_patterns.txt. Use # for a random digit:

• Example: (###) ###-####
• Example: +33 # ## ## ## ##

Step 4: Generate and Verify

Run the code generation to embed the new data into the SDKs:

cd pseudata-poc
task generate

Verify that the new locale appears in:

1. Atomic modules generated in sdks/{language}/resources/locale/fr_fr/data.{ext}
2. Bundles updated to include the new locale (check resources/bundles/world.{ext})
3. AVAILABLE_LOCALES list in each SDK (e.g., sdks/go/resources.go)
4. Regional bundles automatically include the locale if it matches their geography

Fixture-Based Testing

After adding a locale, add a few test cases to the Testing Guide to ensure it’s working correctly across all languages.

Example fixture for French locale:

{
  "name": "city_fr_fr",
  "worldSeed": 42,
  "index": 0,
  "locale": "fr_fr",
  "expected": "Paris"
}

See the Testing Guide for details on how to run and update these tests.