Referring to Locales

Anywhere a locale is named — --ref, --targets, protectedLocales, the keys of a write_translations payload — you may use the locale's code, its language tag, or its file name with the extension. Resolution tries them in that order.

Prefer the Code

Codes are unique by construction. Language tags are not.

A project can declare an informal and a formal German that both carry language: "de-DE". de-DE is then ambiguous: it resolves to the first match, and which one that is depends on the order of your framework's locale array — something you did not choose with this in mind and may reorder without thinking about it.

The precedence rule guarantees one thing only: a locale's own code is never shadowed by a different locale's language tag. Everything else follows from what your project happens to declare.

A Reference That Matches Nothing Is Reported

It is not silently dropped:

{
  "written": ["common.save"],
  "filesWritten": 2,
  "unresolvedLocales": [
    {
      "ref": "de-DE-formal",
      "keys": ["common.save"],
      "suggestion": "Did you mean \"de-formal\" or \"de-DE\" or \"de-DE-formal.json\"?"
    }
  ]
}

unresolvedLocales is the only reliable signal that a write did less than you asked. The key still appears in written, because the other locales did succeed, and filesWritten is simply short by one. A caller checking only written sees success.

A reference matching several locales is reported the same way under ambiguousLocales, naming every candidate and the one that was used.

Both fields are absent when every reference resolves uniquely, so a clean write is byte-for-byte what it always was — adding the reporting did not change the shape of a result that has nothing to report.

Where This Bites

• Protected locales. A protectedLocales entry that resolves to nothing protects nothing, and the run that machine-translates the locale you meant to protect looks exactly like a successful one. See the configuration reference.
• Agent writes. An agent constructing locale keys from a language tag it inferred rather than a code it read from discover is the common way to reach ambiguousLocales.