i18n Helper

A VS Code / Cursor extension for navigating and adding i18n translation keys.

How it works

The extension watches for cmd+click on quoted strings in TypeScript and JavaScript files. It recognises a string as an i18n key if it:

• contains only valid identifier characters (a-z, A-Z, 0-9, _)
• has at least one dot (e.g. common.save, pages.login.title)
• has no spaces

When you cmd+click such a string, one of two things happens:

Key exists

The extension opens en.json and moves the cursor directly to that key's line. For a nested key like components.gigViewButton.copyButton, it navigates through each level of nesting to land on the innermost key.

Key does not exist

A prompt appears:

"pages.newPage.title" not found in en.json   [Add Key]  [Cancel]

If you click Add Key, you're asked to enter the English translation value. The key is then inserted into en.json — creating any missing parent objects along the way — and the file opens with the cursor on the new entry.

Note: when a key is added, the file is re-serialised via JSON.stringify. Key ordering within each object is preserved (V8 maintains insertion order for string keys), but the indentation style is detected from the existing file and matched.

Setup

1. Clone / open this folder in VS Code or Cursor.

2. Install dependencies and compile:

   npm install
   npm run compile

3. Press F5 to launch the Extension Development Host — a second editor window opens with the extension active.

4. In that window, open your project and point the extension at your messages file (see Configuration below).

Install without debug mode (VSIX)

You can package the extension as a .vsix file and install it once, so it runs in your normal editor session instead of the Extension Development Host.

1. From this repo, build and package:

   npm run compile
   npm run vsce

   This produces e.g. i18n-helper-0.1.0.vsix in the project root.

2. Install the VSIX in Cursor or VS Code:

   • Cursor: Open the Command Palette (cmd+shift+P) → Extensions: Install from VSIX... → choose the .vsix file.
   • VS Code: Same, or run: code --install-extension i18n-helper-0.1.0.vsix

   After that, the extension is installed like any other. Bump the version in package.json and run vsce package again when you want to update.

Configuration

All settings live under the i18nHelper namespace and can be set in your workspace's .vscode/settings.json.

i18nHelper.messagesPath

Type	string
Default	packages/shared-frontend/src/i18n/messages/en.json

Path to the source English messages JSON file. Can be:

• Relative — resolved from the workspace root (i.e. the folder you opened in VS Code)
• Absolute — used as-is

Example workspace settings file:

{
  "i18nHelper.messagesPath": "packages/shared-frontend/src/i18n/messages/en.json"
}

Development

npm run watch   # recompile on every save

Then press F5 to open (or reload) the Extension Development Host. Changes take effect after the TypeScript recompiles — no need to restart the host if you're using watch mode, just reload the window (cmd+shift+P → Developer: Reload Window).