Language Codes in Translation Files — i18n File Organization

Translation File Organization

How you name and organize translation files directly impacts developer experience and maintainability. Language codes serve as the primary key for file naming and directory structure.

Common File Naming Patterns

Flat Files (one file per locale)

locales/
├── en.json
├── ja.json
├── de.json
├── zh-Hans.json
└── pt-BR.json

Namespaced Files (split by feature)

locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── ja/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json

Translation File Formats

JSON (most popular for web)

{
  "greeting": "Hello, {{name}}!",
  "items_count": {
    "one": "{{count}} item",
    "other": "{{count}} items"
  }
}

YAML (Ruby on Rails convention)

ja:
  greeting: "こんにちは、{{name}}さん！"
  items_count:
    one: "{{count}}件のアイテム"
    other: "{{count}}件のアイテム"

GNU gettext PO

# Japanese translation
msgid "Hello, %s!"
msgstr "こんにちは、%sさん！"

msgid "%d item"
msgid_plural "%d items"
msgstr[0] "%d件のアイテム"

Popular i18n Libraries and Their Code Conventions

Library	Platform	Locale Format	File Pattern
i18next	JS/TS	BCP 47	{lng}/{ns}.json
react-intl	React	BCP 47	{locale}.json
vue-i18n	Vue	BCP 47	{locale}.json
next-intl	Next.js	BCP 47	messages/{locale}.json
Rails I18n	Ruby	ISO 639-1	{locale}.yml
Django	Python	POSIX	{locale}/LC_MESSAGES/*.po
Flutter ARB	Dart	BCP 47	app_{locale}.arb

Best Practices

1. Use BCP 47 tags for file/directory names (zh-Hans.json, not zh_CN.json)
2. Keep a canonical source locale (usually en.json) as the reference
3. Use ICU MessageFormat for plurals and interpolation
4. Extract strings from code using tools like i18next-parser or formatjs extract
5. Never hardcode locale lists — derive them from the file system
6. Include context comments for translators (many formats support comments)
7. Validate all files have the same keys on CI