i18n Toolkit

Extensão para VS Code/Cursor que adiciona navegação de definição para chaves de tradução em projetos com react-i18next.

Com Cmd/Ctrl + Click (ou F12), você navega da chave para o arquivo de locale correspondente, respeitando contexto de módulo e locale preferido.

Funcionalidades

• Navegação em chamadas de tradução:
  • t('chave')
  • t('namespace:chave')
  • aliases como const { t: tFeature } = useTranslation('feature')
• Navegação em namespace:
  • useTranslation('feature') abre o arquivo da namespace no locale preferido
• Fallback automático de locale:
  • tenta no locale preferido e, se não encontrar, tenta os demais supportedLocales
• Suporte a estruturas comuns de locales:
  • locales/<namespace>/<locale>.ts
  • locales/<locale>/<namespace>.ts
  • cenários aninhados como locales/app/feature/es-ES.ts
• Quick pick opcional quando houver empate de candidatos
• Troca de locale preferido pela command palette e status bar

Exemplo genérico de uso

import { useTranslation } from 'react-i18next';

export const ExampleCard = () => {
  const { t: tFeature } = useTranslation('feature');

  return (
    <>
      <h1>{tFeature('title')}</h1>
      <p>{t('common:description')}</p>
    </>
  );
};

Instalação

Via Marketplace (recomendado)

1. Abra a aba de extensões no VS Code.
2. Busque por i18n Toolkit.
3. Clique em Install.

Via VSIX

1. Gere o pacote:
   • npm run package:vsix
2. Instale na IDE:
   • Extensions -> ... -> Install from VSIX...
3. Selecione o arquivo dentro da pasta versions/

Desenvolvimento local

1. npm install
2. npm run build
3. F5 para abrir o Extension Development Host

Configuração

A extensão lê i18n-toolkit.config.json na raiz do workspace (configurável por setting).

Exemplo:

{
  "defaultNamespace": "global",
  "localesRoot": "src/i18n/locales",
  "localesIndexFile": "src/i18n/locales/index.ts",
  "supportedLocales": ["pt-BR", "en-US", "es-ES", "fr-FR", "de-DE", "it-IT", "ja-JP", "zh-CN", "ru-RU", "ar-SA", "hi-IN", "ko-KR", "nl-NL"],
  "moduleRoots": ["src/modules", "src/components", "src/hooks"],
  "namespaceResolution": {
    "strategy": "resourcesIndexFirst",
    "fallbackToFilesystem": true
  }
}

Settings da extensão:

• i18nToolkit.preferredLocale
• i18nToolkit.configFile
• i18nToolkit.fallbackToQuickPick
• i18nToolkit.enableStatusBarLocaleSwitch

Scripts

• npm run build: compila TypeScript
• npm run test: compila e executa testes
• npm run package:vsix: gera VSIX em versions/ sem prompts interativos
• npm run release:patch: incrementa patch + gera VSIX

Publicação no Marketplace

1. Garanta que o publisher existe no Marketplace.
2. Faça login com vsce login <publisher>.
3. Publique com npx -y -p node@20 -p @vscode/vsce -c "vsce publish".

Performance

A extensão usa cache de índice de namespaces por workspace para evitar reindexação em toda navegação, reduzindo latência em projetos maiores.

Requisitos

• VS Code ^1.90.0

Licença

MIT