How do you translate a Visual Studio Code extension correctly using package.nls.json, package.nls.de.json or other locale variants without breaking its commands and settings? This guide explains VS Code extension localization, manifest placeholders, command labels, vscode.l10n strings and the checks required before publishing a language update.
A VS Code extension has at least two different kinds of text. Static labels declared through package.json contributions can use %key% references to package.nls locale files; messages produced inside extension code use a separate runtime localization workflow. A translation can be grammatically perfect but absent from the Command Palette when these two channels are confused.
The canonical job here is the package.nls.json translation contract for extension manifests, with a clear boundary to vscode.l10n.t and generated runtime bundles. It is not a generic JSON translation guide: this page owns how Visual Studio Code discovers localized extension labels and what makes them testably correct.
- Distinguish manifest contribution labels from extension runtime strings.
- Keep %key% references and JSON key names stable.
- Create the correctly named package.nls locale variants.
- Verify command and configuration labels inside VS Code.
- Test runtime vscode.l10n separately from manifest localization.
The visible problem: a translation that looks correct but fails where it is used
A developer contributes a command with title %myext.open.title% and puts the translated German value in a valid JSON file named package.de.json. The editor does not look for that filename. Even perfect German cannot appear in the Command Palette from that file. Conversely, a TypeScript notification wrapped with vscode.l10n.t does not automatically become a manifest translation just because package.nls.de.json exists.
In practical localization, a bilingual sentence is only one unit of evidence. The file format, the calling program, the user’s locale, the surrounding screen and the published artifact jointly determine whether the meaning arrives. A sentence can be grammatically beautiful yet be unusable if the application cannot find its key, if a resource is packaged for the wrong culture, if a prompt promises a permission the product never needs, or if an installer fails when a translated button contains a reserved character.
Official VS Code localization tooling identifies package.nls.json for static contributions and package.nls.{locale}.json for locale variants. vscode.l10n.t handles code messages with translation bundles and the l10n manifest field. The two paths are connected by product experience but have different extraction, packaging and fallback details. The guide keeps these responsibilities distinct.
First principles: what must remain true
1. Manifest keys are programmatic references
In package.json a contribution label like %myext.command.open% points to a key in package.nls.json. The placeholder syntax is part of VS Code’s extension contract.
The practical test is this: the manifest has the same %key% before and after translation The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
2. The locale filename matters
A translation inside package.nls.de.json is discoverable as German resource content; a similar but arbitrarily named file may not be.
The practical test is this: VS Code loads the intended locale file in a German environment The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
3. Static contributions are not all runtime messages
Command titles and settings descriptions in package.json are static contribution text. Toasts, errors and other messages written in extension code belong to vscode.l10n and associated bundles.
The practical test is this: tests cover both Command Palette labels and runtime messages independently The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
4. Source strings need stable meaning
A short label such as ‘Apply’ may refer to applying edits, a configuration or a patch. The translator must see the command’s function before choosing words.
The practical test is this: the localized command label predicts the action users experience The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
5. Configuration descriptions require precision
A settings label can alter user understanding of default values, side effects, paths and security. An inaccurate translation may cause a bad configuration decision.
The practical test is this: the localized description matches the actual setting behavior and allowed values The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
6. Fallback must be observed, not assumed
Documentation states that missing localized manifest entries can fall back to English. That is useful but not proof of full localization.
The practical test is this: a review report separates translated values from English fallback The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
7. Code placeholders have their own rules
vscode.l10n.t supports positional and named arguments for runtime messages, which are distinct from %key% manifest placeholders.
The practical test is this: each call displays its dynamic values correctly in the target language The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
8. Packaging is part of correctness
Local builds can reference files that are accidentally excluded from a published extension package. Review the shipped extension rather than editor workspace alone.
The practical test is this: a clean installation of the published VSIX or equivalent artifact displays the target strings The principle applies before polishing style, because a visually attractive translation cannot compensate for a different application behavior. Keep the original sample, its intended context and the target rendering together. When two reviewers disagree, the output behavior and declared purpose are better evidence than a dictionary synonym or a screenshot without state information.
A repeatable twelve-stage method
Stage 1: Collect user-facing text
Inventory package.json contributions and all runtime UI strings, separating them by localization channel.
Evidence to keep: a manifest-vs-runtime string inventory This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 2: Find manifest placeholders
Search contribution titles, descriptions, menus and settings for literal strings and %key% references.
Evidence to keep: a source file with each localizable contribution identified This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 3: Set the base package.nls.json
Create a stable mapping from keys to default-language values used by the manifest.
Evidence to keep: a key-to-source mapping with no duplicates This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 4: Create locale files
Use the package.nls.{locale}.json naming convention supported by VS Code.
Evidence to keep: one locale-qualified file per intended target This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 5: Give translators behavior context
Record what each command invokes, whether a setting is reversible and what values it accepts.
Evidence to keep: an annotated command and settings catalogue This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 6: Protect JSON syntax
Preserve double quotes, keys, commas and escaping while changing the values.
Evidence to keep: parseable JSON and matching key sets This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 7: Handle command terminology
Prefer clear imperative or action descriptions suitable for Command Palette search.
Evidence to keep: a user test distinguishing similarly named commands This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 8: Handle settings wording
Translate defaults, warnings and feature scope without promising unavailable behavior.
Evidence to keep: a setting-by-setting comparison to implementation This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 9: Separate runtime messages
Use vscode.l10n.t and its documented bundle generation path for strings in extension code.
Evidence to keep: an inventory of runtime calls and target bundles This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 10: Test language selection
Launch VS Code in each supported display language and reload the extension where necessary.
Evidence to keep: screenshots of actual localized contribution labels This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 11: Build the extension package
Check packaging includes package.nls and l10n assets rather than relying on workspace files.
Evidence to keep: inspection of shipped artifact contents This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Stage 12: Rehearse failure and fallback
Remove one noncritical translated key in a controlled test, then observe fallback and report missing coverage.
Evidence to keep: a reproducible missing-key and source-locale test This stage should produce an observable artifact—a checked identifier, a test output, a paired screenshot, a build report, a locale-specific review note or a signed-off string record. An opinion without the artifact is a hypothesis, not release verification. If the result contradicts the intended meaning, correct the cause and rerun the same test rather than merely changing the target wording.
Worked examples: what correct translation looks like under real constraints
The cases below use invented demonstration strings and projects. They are teaching examples, not statements that a particular vendor’s live product uses those strings. Each case separates the language decision from the file decision and the release decision. Read the source, identify what may change, change only the permitted surface, then explain how a reviewer could disprove the proposed fix.
Worked case 1: A localized command title
Source situation. The manifest uses %myext.hello.title% for a command. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translator edits the token rather than its corresponding value. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Keep %myext.hello.title%; translate its value in package.nls.de.json. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Search the Command Palette after changing display language. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 2: A settings description
Source situation. Extension contributes a setting that enables background syncing. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Loose translation implies user files are never sent to a service. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Explain true network behavior and keep defaults accurate. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Toggle setting and compare observable result. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 3: An invalid locale filename
Source situation. A translator creates package.nls.german.json. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. VS Code does not recognize intended language selection. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Use the supported locale identifier as a filename segment. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Inspect behavior in a German VS Code session. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 4: A missing locale key
Source situation. The target file omits one command label. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. English fallback is mistaken for completed translation. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Mark the key as missing; add a reviewed translation. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Compare source and target key inventories. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 5: An escaped quotation mark
Source situation. A translated description needs embedded quotation marks. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Removing JSON escaping makes a file unparsable. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Use proper JSON string escaping and check the rendered label. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Parse locale JSON and open settings UI. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 6: A code notification
Source situation. Extension code calls vscode.l10n.t for a save message. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. The developer adds text only to package.nls resources. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Translate the runtime message through the documented l10n bundle workflow. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Trigger notification after installation in target locale. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 7: A positional runtime variable
Source situation. Message is ‘Updated {0} files’. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translation swaps count text but drops the placeholder. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Retain the indexed argument according to message semantics. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Test with 0, 1 and multiple files. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 8: A named runtime variable
Source situation. Code calls vscode.l10n.t with a {name} argument. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translator changes name token to an unrelated word. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Preserve the named argument while adapting syntax around it. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Render with long and non-Latin names. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 9: A setting key as visible text
Source situation. The identifier myext.safeMode is shown in documentation. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translation rewrites the identifier inside copy-paste instructions. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Keep literal configuration identifiers unchanged and explain them in target prose. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Copy the documented setting key into settings JSON. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 10: A very long command title
Source situation. A German or Finnish target expands beyond initial UI width. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. The command label truncates to the same prefix as another command. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Choose a clear distinguishing term and test palette search. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Compare two similar commands at minimum width. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 11: A shortcut description
Source situation. A command label names a keyboard gesture. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Localization replaces shortcut letters according to a different platform. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Confirm actual VS Code keybindings instead of translating raw chord tokens. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Trigger with keyboard on Windows, macOS and Linux where supported. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 12: A menu category
Source situation. The extension registers a category and several command titles. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Category is translated inconsistently across related commands. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Establish one approved category term and keep individual actions distinct. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Search by category and inspect all command titles. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 13: A command identifier
Source situation. Manifest command ID is myext.openFile. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translator localizes ID and breaks command registration. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Leave machine command IDs unchanged; translate only its title. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Invoke the registered command programmatically and from the palette. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 14: Missing package metadata
Source situation. A translation exists in workspace but is excluded from published files. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Local testing succeeds, marketplace install falls back. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Inspect the packaged VSIX for locale files. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Install the artifact in a clean VS Code profile. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 15: A disabled setting
Source situation. The setting description says the feature is always active. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. The actual default is false. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Correct wording to reflect explicit opt-in behavior. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Compare default, enabled and disabled states. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 16: A multi-language help link
Source situation. A localized setting description links to English-only help. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Language mismatch may confuse but must not invent target documentation. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Label the destination accurately and link to verified localized help if available. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Open link from target environment and inspect landing language. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 17: An inaccessible command label
Source situation. Screen reader announces an unclear abbreviated title. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Shortening removed essential action semantics. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Use clear accessible wording, then test keyboard and screen reader navigation. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Navigate Command Palette without visual context. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 18: A pseudo-localization pass
Source situation. Developer stress-tests labels with expanded characters. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Pseudo target is mistaken for a polished translation. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Use it to detect clipping and untranslated literals, not for language approval. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Run a separate human review of real target strings. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 19: An extension activation message
Source situation. The welcome notification includes the active locale name. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. A string is built with concatenation and cannot reorder grammar. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Move translatable sentence into a complete l10n message with a placeholder. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Test different locale display names and lengths. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 20: An update to extension contributions
Source situation. A new command is added without a base NLS entry. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. The manifest resolves an English literal in some places. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Make the base key inventory a build-time check. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Create a release diff of added and removed contribution keys. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 21: A locale fallback chain
Source situation. User selects a regional display language. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. Translator assumes region-specific resource must always exist. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Test exact language resolution and document observed fallback. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Record requested locale, loaded file and displayed label. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Worked case 22: An older package after upgrade
Source situation. VS Code is updated but the extension still carries stale target assets. The translation request is not complete until the reviewer knows who sees this message, which part is a resource identifier, and what application state activates the text.
Hidden risk. New labels appear in English after an extension release. A word-for-word draft may look plausible in isolation while changing the user promise, suppressing a required variable, shifting a file reference, or displaying the right language in the wrong context. Do not approve it from a bilingual spreadsheet alone.
Corrected approach. Regenerate and repackage target files with the new version. Preserve system-controlled tokens exactly as the specification requires; translate user-facing language for clarity and audience; record any deliberate deviation and why it improves functional equivalence rather than merely stylistic preference.
Proof and transfer. Use clean-install regression testing across supported releases. Repeat the check with a second locale and an awkward input such as a long label, unfamiliar name, empty field or different number. The goal is not to force a single wording across every language. It is to confirm that the same operation, choice and outcome remain understandable when the surrounding assumptions change.
Failure modes: how to diagnose and recover
Failure 1: Manifest placeholders were edited
How it appears: Command titles appear as unresolved markers or fail lookup. Restore the %key% reference and corresponding NLS key. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 2: Wrong NLS filename
How it appears: A target language remains English despite valid JSON. Follow package.nls.{locale}.json filename convention. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 3: Static and runtime strings mixed
How it appears: Command Palette translates while notifications do not. Use vscode.l10n for code messages, package.nls for contributions. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 4: Incomplete key coverage
How it appears: Some target labels silently fall back. Count base and locale keys separately and track omissions. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 5: JSON parser failure
How it appears: An unescaped quote makes the locale resource invalid. Validate JSON before packaging. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 6: Setting semantics drift
How it appears: Translation describes the opposite of the actual default. Test real setting behavior, not just terminology. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 7: Missing package assets
How it appears: Local tests succeed but published users cannot see translations. Inspect VSIX contents and deployment include rules. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 8: Placeholder corruption
How it appears: Runtime messages show missing counts or raw variable names. Preserve documented vscode.l10n.t arguments. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 9: Inconsistent command verbs
How it appears: Two commands have identical-looking target labels. Test action distinction and choose concise, differentiated words. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 10: Hardcoded source text
How it appears: A manifest contribution bypasses localization keys. Move localizable text into the NLS mapping. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 11: Untranslated menu category
How it appears: A command title translates but category stays English. Inventory related contribution fields and update their resources. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Failure 12: Language switch not tested
How it appears: Approval depends solely on static files. Launch the installed extension in each intended display language. Start recovery from the smallest reproducible example. Compare the exact source and target artifact, not a memory of an earlier version. If the defect affects identities, data permissions, installation state or error recovery, hold release until a subject-matter reviewer and the implementer agree what action the interface actually performs.
A robust correction changes one cause at a time and rechecks the original trigger after rebuilding or reloading the localized artifact. It also asks whether adjacent strings inherit the same defect. Record the language, platform version, key or resource path, screenshot or log and fix owner so the issue does not reappear in a subsequent language release.
Practice and transfer: test your own decisions
Exercise 1: Protect %key% syntax
Try it: Translate a command title referenced in package.json. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Keep key and change locale value only. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 2: Test target filename
Try it: A file is named package.nls.france.json. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Rename to a supported locale identifier and verify lookup. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 3: Translate setting consequences
Try it: A switch controls cloud synchronization. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Explain opt-in, data movement and default behavior accurately. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 4: Distinguish runtime from manifest
Try it: A notification appears after saving a file. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Use vscode.l10n.t rather than manifest NLS. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 5: Validate JSON escapes
Try it: A string contains double quotation marks. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Parse source and target JSON before release. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 6: Repair missing key coverage
Try it: One target locale omits a new menu title. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Add reviewed text and note English fallback before the fix. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 7: Exercise a long command
Try it: A label expands in translation. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Check Command Palette search, truncation and distinction. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 8: Test a named argument
Try it: Runtime message includes {userName}. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Keep named placeholder and test non-Latin input. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 9: Inspect packaging
Try it: Translation works in the repository but not after install. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Verify asset inclusion and clean-profile behavior. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Exercise 10: Write a release matrix
Try it: Extension supports three display languages. Before reading the guidance, name the invariant data, the translatable text, the runtime condition and a concrete way to show failure. Show exact files, tests, runtime coverage and reviewer status. An acceptable answer must be testable by another person who did not attend the discussion; ‘seems natural’ is not sufficient when technical content or permissions are involved.
Frequently asked questions
What is package.nls.json?
It is the base localization mapping for static user-facing contributions declared by a VS Code extension’s package.json manifest.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
How do I create another language?
Create a supported package.nls.{locale}.json file with the same stable keys and reviewed target strings, then verify it in VS Code.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
What does %key% do in package.json?
The percent-delimited reference tells the extension manifest localization system to find a user-visible string by key.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
Can I translate the %key% marker?
Do not change the key’s identity unless engineering also intentionally migrates the reference. Translate the resource value.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
Is vscode.l10n.t the same as package.nls.json?
No. vscode.l10n.t localizes messages in extension code, while package.nls files cover static contribution text in the manifest.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
What happens when a target NLS key is missing?
VS Code documentation describes fallback to the base English value for missing entries. Missing keys still count as incomplete coverage.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
Do locale files have to be valid JSON?
Yes. Keys and values require correct JSON syntax and escaping, even when the translated wording itself is excellent.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
Why is the package important?
A file present in a development folder may be absent from a shipped VSIX or release. Verify installed behavior.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
Can I use machine translation only?
Machine translation can help draft labels, but human review of command purpose, setting behavior and interface context remains necessary.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
How should I test a language change?
Inspect the installed extension’s commands, settings, menus and runtime notifications under the intended VS Code display language.
For a reliable decision, keep the original and localized output beside the specification that controls the behavior. Test the smallest example first, then repeat it in a complete build or published package. Treat translation approval and technical validation as complementary, not interchangeable, activities.
A practical release checklist
- Identify the message’s true purpose, audience and trigger.
- Record all protected keys, variables, data values and code-like syntax.
- Confirm what the target language is allowed to change.
- Verify strings with a second independent reviewer.
- Run a syntax or build validation for the actual platform.
- Test a full user journey in at least two locales.
- Capture long-string, missing-string and right-to-left edge cases where relevant.
- Retest the default fallback and incomplete localized files.
- Inspect final packaging rather than only source files.
- Track the approved version, reviewers and known exceptions.
- Release only after the user-facing action matches the source intention.
- Retain a regression test for the next content or tool update.
The best VS Code extension translation is observable in the user’s actual editor. Static contribution keys, locale-specific NLS files and runtime l10n bundles each have a job. Keeping them separate gives the translator enough context to write natural commands and gives engineering a precise way to check that the right sentence is delivered through the right mechanism.
Source documents and contextual next routes
Read the platform documentation: Microsoft VS Code localization tooling; VS Code Extension API l10n; VS Code contribution points. Standards and developer documentation explain the machinery; examples here explain how to apply it to translation and validation.
For adjacent resource-file problems, use JSON resource bundles, YAML locale files, Apple Xcode string catalogs, and Java ResourceBundle fallback. For release drift across locales, read CLDR version and release QA. To deepen the language foundation, continue at the Vocabulary Learning Hub and How English Works. These routes serve different search intentions: lexical learning, language structure, neighboring resource formats and release verification; none replaces this guide’s platform-specific job.