Skip to content

I18N.md

Latest commit

 

History

History
230 lines (171 loc) · 8.42 KB

I18N.md

File metadata and controls

230 lines (171 loc) · 8.42 KB

String‑LE Internationalization (I18N) Guide

Goals and philosophy

  • Inclusive by default: all user‑facing text is localizable.
  • Privacy‑first and offline: no network calls; translations ship with the extension.
  • Predictable keys: two namespaces — manifest.* for package.json UI and runtime.* for in‑code strings.
  • Safe fallbacks: English is bundled and used when a key or locale is missing.
  • Translator‑friendly: consistent placeholders, small focused sentences, and a source language.json catalogue.

Non‑goals:

  • Remote translation fetching or telemetry.
  • Complex runtime pluralization logic. We use positional {0} placeholders with vscode-nls.

File layout

src/i18n/
  package.nls.de.json
  package.nls.es.json
  package.nls.fr.json
  package.nls.id.json
  package.nls.it.json
  package.nls.ja.json
  package.nls.ko.json
  package.nls.pt-br.json
  package.nls.ru.json
  package.nls.uk.json
  package.nls.vi.json
  package.nls.zh-cn.json
  language.json            # source catalogue of English strings (see API below)

package.nls.json           # base English manifest/runtime keys
package.json               # wired to l10n; copies localized files on publish

Notes:

  • During packaging, src/i18n/package.nls*.json files are copied to the extension root by the vscode:prepublish script so VS Code can discover them.
  • VS Code discovers manifest translations based on the l10n field in package.json and the package.nls*.json naming convention.

Supported locales out of the box:

Locale File
German package.nls.de.json
Spanish package.nls.es.json
French package.nls.fr.json
Indonesian package.nls.id.json
Italian package.nls.it.json
Japanese package.nls.ja.json
Korean package.nls.ko.json
Portuguese (Brazil) package.nls.pt-br.json
Russian package.nls.ru.json
Ukrainian package.nls.uk.json
Vietnamese package.nls.vi.json
Chinese (Simplified) package.nls.zh-cn.json

Key namespaces

Manifest prefix: manifest.*

Used by package.json contributions (commands, configuration, menus, capabilities):

{
  "displayName": "%manifest.ext.name%",
  "description": "%manifest.ext.desc%",
  "contributes": {
    "commands": [
      {
        "command": "string-le.extractStrings",
        "title": "%manifest.command.extract.title%",
        "category": "%manifest.command.category%"
      }
    ]
  }
}

Translations map 1:1 in package.nls.json and per‑locale files:

{
  "manifest.ext.name": "String-LE",
  "manifest.command.category": "String-LE",
  "manifest.command.extract.title": "String-LE: Extract"
}

Runtime prefix: runtime.*

Used in TypeScript via vscode-nls with MessageFormat.file:

import * as nls from 'vscode-nls'
const localize = nls.config({ messageFormat: nls.MessageFormat.file })()

// Example usages
const tooltip = localize('runtime.status.tooltip', 'Run String-LE: Extract')
const warn = localize('runtime.message.warn.large-file', 'Large file detected ({0} bytes). Extraction may take longer.', fileSize)

Placeholders are positional: {0}, {1}, … and must be preserved by translators.

language.json (API reference)

Purpose: a translator‑friendly catalogue of canonical English phrases used across both manifest and runtime. This file is not parsed at runtime by the extension; it exists to help maintain coverage and drive translation workflows and checks.

Format:

  • Newline‑delimited plain text, one phrase per line.
  • No JSON object/array wrapping; .json extension chosen for editor syntax and tooling convenience.
  • Lines should be exact English source messages, including punctuation and placeholder tokens like {0}.

Contract:

  • Duplicates are allowed if the same phrase appears in multiple contexts.
  • Do not translate this file; create/update per‑locale package.nls.{locale}.json instead.
  • When adding/removing user‑facing strings in code or package.json, update:
    • package.nls.json with the new key/value (English)
    • src/i18n/language.json with the raw English phrase
    • Any existing locale files you can confidently translate; others will gracefully fall back to English

Validation (recommended):

  • CI or local scripts can diff language.json against the values in package.nls.json to detect missing coverage.

Example excerpt:

String-LE: Extract
Large output ({0} lines). Proceed?
Run String-LE: Extract
Copied to clipboard

Authoring localized strings

Guidelines:

  • Keep sentences short and unambiguous.
  • Use sentence case and consistent terminology.
  • Prefer verbs for actions (Extract, Copy, Open) and descriptive titles for prompts.
  • Always pass an English default to localize(key, default, ...args); this is used as the fallback string.
  • Use positional placeholders {0}, {1} and provide values in the same order in code.
  • Avoid embedding quotes unless necessary; prefer readable punctuation and Unicode arrows where already used.
  • Do not hardcode user‑visible text in code; route through localize(...).

Anti‑patterns:

  • Concatenating translated fragments at runtime.
  • Using different English defaults for the same key.
  • Reusing keys for different messages (keys identify semantics, not just text).

Accessibility:

  • Avoid color‑only cues; ensure messages are clear in any theme.
  • Keep technical warnings concise and actionable.

Adding a new locale

  1. Create src/i18n/package.nls.<locale>.json (e.g., package.nls.pl.json).
  2. Copy all keys from package.nls.json and translate values.
  3. Keep placeholders {0} intact and in order.
  4. Build and run to verify (see Testing below). Packaging will copy files to the root automatically.

Locale naming follows VS Code’s conventions (e.g., de, pt-br, zh-cn).

Testing and verification

Local testing:

  • Change VS Code display language via “Configure Display Language” or run the Extension Development Host with a locale, e.g. --locale=fr.
  • Ensure manifest UI (command titles, settings descriptions) reflect translations.
  • Trigger runtime strings (status bar, notifications, prompts) to verify placeholders and grammar.

Automation suggestions:

  • Lint: verify all manifest.* and runtime.* keys exist across locale files.
  • Coverage: compare values in package.nls.json against language.json to detect missing source phrases.
  • Build check: ensure npm run vscode:prepublish copies src/i18n/package.nls*.json to the root.

Build and packaging

  • package.json contains "l10n": "./package.nls.json" for VS Code to locate the base strings.
  • The vscode:prepublish script runs: npm run build && cp src/i18n/package.nls*.json . so Marketplace packages include all locales at the root.
  • No runtime network access is required; everything ships inside the .vsix.

Troubleshooting

  • Seeing English instead of your language: the key is missing in your locale file; fallback to English is expected.
  • Placeholders not replaced: ensure the message uses {0} style tokens and code passes arguments to localize(...).
  • Incorrect grammar or spacing: propose an update to the relevant package.nls.<locale>.json.

Reference: common keys

Examples of frequently used keys and messages (see package.nls.json for the canonical list):

Key Example English
runtime.status.tooltip Run String‑LE: Extract
runtime.message.info.no-strings No strings found
runtime.message.warn.large-file Large file detected ({0} bytes). Extraction may take longer.
runtime.dialog.action.copy Copy only
manifest.command.extract.title String‑LE: Extract
manifest.settings.sort.mode.option.alpha-asc Alphabetical (A → Z)

Security & privacy

  • No data leaves your machine for localization purposes.
  • Telemetry is local‑only when enabled; it does not include message contents.

Project: Issues • Pull Requests • Releases • MIT License

Dev: Spec • Architecture • Development • Troubleshooting

Docs: Commands • Notifications • Status Bar • Config • Performance • I18N • Privacy