Translation keys that stay consistent across a whole app
How localize.dev names keys, reuses them for repeated text, keeps short ambiguous copy apart, and notices when source text changes after it was translated.
Stephen Ufort · November 6, 2026 · 2 min read

Hand-written keys drift. One person writes save_button, another buttons.save, a third common.actions.save, and three keys hold the same word. Asking a coding agent to extract strings one file at a time drifts the same way, because each file starts without knowing the keys the others made.
localize.dev names keys for the whole app in one run, and it remembers them for the next run. This post covers how.
Who names the key
The model proposes each key from the file path, the component and the string. The rules it gets are short: lowercase snake case segments joined by dots, a namespace for the feature or screen, and a name for what the string does, not a transliteration of it. src/components/AuthForm.tsx gives auth.*; a heading becomes auth.welcome_heading, not auth.welcome_back_we_missed_you.
Everything after that is code. Each proposed key is cleaned up and registered. If two different strings get the same name, the second one gets a _2 suffix, and a key that would clash with an existing branch of the locale file is renamed so neither one overwrites the other.
The same text gets the same key
Before a string is sent to the model, the engine checks whether that text already has a key, either in your source locale file or from earlier in the same run. If it does, the code calls that key again and the model never sees the string. A run reports these as reused keys, counting every place the text appears, so ten “Cancel” buttons are ten reuses of one key.
Short copy that means two things
Reuse by text alone is wrong for short copy. “Post” on a button is a verb, and in a card title it’s a noun. Many languages use different words for each.
So copy of three words or fewer, up to 40 characters, with no placeholders or tags, gets a sense alongside its text: the element and the attribute it sits in, such as button or input[placeholder]. “Post” on a <button> and “Post” in an <h3> become separate messages, and each one is sent with a hint about where it appears.
"placeholder" attribute on <input> in component <Login>
element text inside <button> in component <Composer>When the translations of the two senses come back the same in every language, they merge back into one key. When they differ, both keys stay. You only get a second key where a language actually needs one.
Knowing when source text changed
Keys only help if their translations stay in step with the source. When someone changes “Save” to “Save changes” in en.json, every translation of that key is out of date, but nothing in the file says so.
localize.lock.json records a fingerprint of each source message at the time it was translated: the first 12 hex characters of its SHA-256. Commit it with your code. On the next run, a message whose fingerprint no longer matches is translated again, and localize-dev check fails in CI with an “Outdated translations” error that names the keys.
Keys in other stacks
Not every stack uses dotted keys. Laravel’s JSON files and gettext catalogs use the source text itself as the key, so localize.dev does too. Flutter’s ARB keys are camelCase and Android’s are snake_case, because that’s what their tools expect.
Try it on your own code in the playground, no account needed