Broadest Localization Scope

Define every localization key at the broadest scope where its meaning is reusable. When a key becomes useful in another process or part, move it to the broader scope and remove the narrower definition. A domain-neutral term with an ordinary, public meaning belongs in the development core even when only one part currently uses it. Place keys shared across parts and processes in development core; API-only keys in API core; panel-only keys in panel core; and site-only keys in site core. Within a part, place keys shared by its API, panel, and site under common, and use api, panel, or site only for process-specific keys.

Correct

// Shared across parts and processes: core/localization/en.json
{ "coreDone": "Done" }

// Domain-neutral and public despite currently being used by one part: core/localization/en.json
{ "coreStep": "Step" }

// Shared across API parts: api/localization/en.json
{ "serverError": "A server error occurred." }

// Used only by panels: panel/localization/en.json
{ "coreShowPrompts": "Show prompts" }

// Shared across site parts: site/localization/en.json
{ "coreReturnHome": "Return home" }

// Shared by a part's API, panel, and site: blog/localization/en.json
{ "common": { "author": "Author" } }

// Used only by a part's site process: accounts/localization/en.json
{ "site": { "editProfile": "Edit your profile" } }

Incorrect

// Wrong: a key shared by all part processes is placed only under panel
{ "panel": { "author": "Author" } }

// Wrong: an ordinary, domain-neutral term is kept in the part that first uses it
{ "marketing": { "common": { "step": "Step" } } }

Exceptions

• Keep an otherwise general term in a part when that part gives it a distinct domain-specific meaning.