VS Code
The x18n extension brings the x18n language server into VS Code. All i18n logic lives in the server. The extension shows the results: annotations, views, the status bar and the UI panel.
Install "x18n" by antfu from the VS Code Marketplace or Open VSX. The extension id is antfu.x18n-vscode. It needs VS Code 1.100 or later.
The extension starts in a workspace that has an x18n.config.* file or a package.json. It reads the same config as the CLI, so the editor and x18n check report the same diagnostics.
In-place annotations
An in-place annotation hides a key in code and shows its value in the display locale. The display locale is the locale that annotations and hovers show. It is your own choice, and it defaults to the source locale.
- The raw key shows again on the cursor line and inside a selection.
- A key that is missing in the source locale shows in a warning color.
- Values longer than
x18n.annotationMaxLengthare cut. In in-place mode, such a value shows as a hint after the key. - Run "x18n: Toggle In-place Annotations" to switch between in-place mode and hints after the key.
- With
x18n.annotationInPlaceFullMatch, the value replaces the whole call, such ast('key', { n }), instead of only the key. Calls over several lines keep the key-only replacement. - The
x18n.theme.*settings set the colors and borders of in-place values and missing keys. Empty settings use the colors of your theme.
Locales show with their flag in the views, the locale pickers, hovers and the status bar. Set x18n.showFlags to false to hide the flags.
The status bar shows the display locale. Click it, or run "x18n: Set Display Locale", to change it.
Keys as symbols
The extension treats a key such as t('settings.title') like an imported symbol:
- Go to definition opens the message in the source locale.
- Go to implementation lists the message in every locale.
- Find all references lists every usage in code. It does not list the locale files; use Go to implementation for those.
- Rename (F2) renames the key in every locale file and every usage. On a parent key, it renames every key under it.
- Completion suggests keys inside translate calls.
These features work in code and in locale files. The results show next to the results of TypeScript.
Hovers, diagnostics and quick fixes
A hover on a key shows its value in each locale and the number of usages, with links to open the key in the UI, to copy a translate prompt, and to translate it with an agent. Diagnostics are the same as the ones from x18n check. Quick fixes come from the checks, for example "Add the key to the source locale" or "Copy the source value". Code actions also extract a hard string, extract every hard string of the file, or add an ignore comment for a string.
Views
The x18n view container in the activity bar has four views:
- Current File: the keys of the open file, with their values.
- Progress: translation progress per locale.
- Keys: the key tree of the project. Edit, open, delete, copy a prompt or translate with an agent from the context menu of a key.
- Usage Report: unused keys, and used keys that are not defined.
UI panel
"x18n: Open UI" opens the x18n UI in a panel. The language server starts the UI server on loopback and passes a one-time token to the panel, so you do not enter an auth code. "x18n: Open Key in UI" opens the UI at one key.
Translate with an agent
"x18n: Translate with Agent" opens the editor's chat in agent mode with the translate prompt for a locale, or for one key from a hover or the Keys view. The agent translates the messages, writes them with x18n apply and runs x18n check, as the prompt says. x18n itself calls no model. The agent needs the x18n CLI in the project. In an editor without the VS Code chat, the command copies the prompt instead.
Config files
The extension validates x18n.config.json against the config schema. With the Red Hat YAML extension installed, it also validates x18n.config.yml, x18n.config.yaml and *.x18n-plugin.yml files.
Migration from i18n-ally
If a folder has i18n-ally.* (or i18n-ally-next.*) settings in .vscode/settings.json and no x18n.config.* file, the extension offers to migrate. It opens the files that it will write, and writes them only after you confirm. You can also run "x18n: Migrate from i18n-ally" from the command palette. See Migration from i18n-ally.
Commands
| Command | Title |
|---|---|
x18n.openUi | x18n: Open UI |
x18n.openKey | x18n: Open Key in UI |
x18n.setDisplayLocale | x18n: Set Display Locale |
x18n.editKey | x18n: Edit Message |
x18n.renameKeyPrefix | x18n: Rename Key Prefix |
x18n.deleteKey | x18n: Delete Key |
x18n.extract | x18n: Extract Hard String |
x18n.extractFile | x18n: Extract All Hard Strings in File |
x18n.copyTranslatePrompt | x18n: Copy Translate Prompt |
x18n.translateWithAgent | x18n: Translate with Agent |
x18n.goToNextUsage | x18n: Go to Next Key Usage |
x18n.goToPrevUsage | x18n: Go to Previous Key Usage |
x18n.toggleInPlace | x18n: Toggle In-place Annotations |
x18n.restartServer | x18n: Restart Language Server |
x18n.migrateFromI18nAlly | x18n: Migrate from i18n-ally |
x18n.showOutput | x18n: Show Output |
Settings
Project settings live in the config file. The VS Code settings change only the editor experience, and never override the config.
| Setting | Description | Type | Default |
|---|---|---|---|
x18n.enabled | Run the x18n language server in this workspace. | boolean | true |
x18n.useLocalServer | Run the @x18n/lsp installed in the workspace's node_modules instead of the bundled server, when there is one. Restart the server after changing this. | boolean | true |
x18n.annotations | Show translated values next to or in place of keys in code. | boolean | true |
x18n.annotationInPlace | Replace keys in code with their display-locale value. The raw key shows on the cursor line and inside selections. | boolean | true |
x18n.annotationInPlaceFullMatch | In in-place mode, replace the whole translate call, such as t('key', { n }), instead of only the key. Keys whose call is not known keep the key-only replacement. | boolean | false |
x18n.annotationMaxLength | Longest value shown in an annotation. Longer values are truncated, and in-place mode falls back to an after-key hint. | number | 40 |
x18n.displayLocale | Locale shown in annotations. Empty means the source locale. | string | "" |
x18n.showFlags | Show the flag of each locale in views, pickers, hovers and the status bar. | boolean | true |
x18n.theme.annotation | CSS color of in-place values. Empty uses the inlay hint color of the theme. | string | "" |
x18n.theme.annotationMissing | CSS color of keys without a value. Empty uses the warning color of the theme. | string | "" |
x18n.theme.annotationBorder | CSS border color of in-place values. Empty draws no border. | string | "" |
x18n.theme.annotationMissingBorder | CSS border color of keys without a value. Empty draws no border. | string | "" |
x18n.theme.annotationInPlaceFullMatch | CSS color of values that replace a whole call (x18n.annotationInPlaceFullMatch). Empty uses x18n.theme.annotation. | string | "" |
x18n.codeLens | Show usage counts and missing locales above keys in resource files. | boolean | false |
x18n.trace.server | Trace the communication between VS Code and the x18n language server. | string | "off" |
Other editors
The language server works in any editor with an LSP client. See LSP protocol.