Internacionalização (i18n) em TypeScript

Internacionalização (i18n) em TypeScript com a biblioteca i18next

\n\n

Internacionalização (i18n) é o processo de desenvolvimento de uma aplicação que pode se adaptar a diferentes idiomas e padrões regionais sem alterar o código-fonte. Para aplicações TypeScript, uma das bibliotecas mais poderosas e populares é o i18next. Ela suporta todos os frameworks modernos (React, Vue, Angular) e oferece suporte de primeira classe para TypeScript, permitindo criar traduções com segurança de tipos.

\n\n

Instalação e configuração básica

\n\n

Para começar, instale os pacotes i18next e os backends necessários. No exemplo abaixo, é usado um backend de arquivos para carregar arquivos JSON com as traduções:

\n\n

npm install i18next i18next-fs-backend\n# Para React, adicionalmente:\nnpm install react-i18next

\n\n

Crie um arquivo de configuração i18n.ts:

\n\n

import i18n from 'i18next';\nimport Backend from 'i18next-fs-backend';\nimport { initReactI18next } from 'react-i18next';\n\ni18n\n  .use(Backend)\n  .use(initReactI18next)\n  .init({\n    fallbackLng: 'ru',\n    debug: process.env.NODE_ENV === 'development',\n    interpolation: {\n      escapeValue: false,\n    },\n    backend: {\n      loadPath: '/locales/{{lng}}/{{ns}}.json',\n    },\n  });\n\nexport default i18n;

\n\n

Estrutura dos arquivos de tradução

\n\n

Crie a pasta public/locales com subpastas para cada idioma. Por exemplo:

\n\n

public/locales/ru/translation.json
public/locales/en/translation.json

\n\n

Exemplo de conteúdo do arquivo ru/translation.json:

\n\n

{\n  "greeting": "Привет, {{name}}!",\n  "items": "У вас {{count}} сообщение",\n  "items_plural": "У вас {{count}} сообщений",\n  "nested": {\n    "title": "Заголовок",\n    "description": "Описание"\n  }\n}

\n\n

Versão em inglês en/translation.json:

\n\n

{\n  "greeting": "Hello, {{name}}!",\n  "items": "You have {{count}} message",\n  "items_plural": "You have {{count}} messages",\n  "nested": {\n    "title": "Title",\n    "description": "Description"\n  }\n}

\n\n

Tipagem de traduções em TypeScript

\n\n

Uma das principais vantagens do i18next é a tipagem estrita. Crie um arquivo types/i18n.d.ts:

\n\n

import 'i18next';\n\ndeclare module 'i18next' {\n  interface CustomTypeOptions {\n    defaultNS: 'translation';\n    resources: {\n      translation: {\n        greeting: string;\n        items: string;\n        items_plural: string;\n        nested: {\n          title: string;\n          description: string;\n        };\n      };\n    };\n  }\n}

\n\n

Agora o TypeScript verificará as chaves de tradução em tempo de compilação. Se você tentar usar uma chave inexistente, receberá um erro.

\n\n

Uso em componentes React

\n\n

A biblioteca react-i18next fornece o hook useTranslation e o componente Trans:

\n\n

import { useTranslation } from 'react-i18next';\n\nfunction Welcome() {\n  const { t, i18n } = useTranslation();\n\n  const changeLanguage = (lng: string) => {\n    i18n.changeLanguage(lng);\n  };\n\n  return (\n    <div>\n      <h2>{t('greeting', { name: 'Иван' })}</h2>\n      <button onClick={() => changeLanguage('en')}>English</button>\n      <button onClick={() => changeLanguage('ru')}>Русский</button>\n    </div>\n  );\n}

\n\n

Pluralização e interpolação

\n\n

O i18next suporta regras complexas de plural. Em russo, há três formas (1, 2-4, 5+), em inglês, duas. A biblioteca seleciona automaticamente a forma correta com base no número:

\n\n

// No arquivo de tradução (ru):\n{\n  "apple": "{{count}} яблоко",\n  "apple_plural": "{{count}} яблока",\n  "apple_plural_2": "{{count}} яблок"\n}\n\n// Uso:\nconst