Internacionalización (i18n) en TypeScript: biblioteca i18next

Internacionalización (i18n) en TypeScript con la biblioteca i18next

\n\n

La internacionalización (i18n) es el proceso de desarrollar una aplicación que pueda adaptarse a diferentes idiomas y estándares regionales sin modificar el código fuente. Para aplicaciones TypeScript, una de las bibliotecas más potentes y populares es i18next. Es compatible con todos los frameworks modernos (React, Vue, Angular) y ofrece soporte de primera clase para TypeScript, lo que permite crear traducciones con seguridad de tipos.

\n\n

Instalación y configuración básica

\n\n

Para empezar, instale los paquetes i18next y los backends necesarios. En el siguiente ejemplo se utiliza un backend de archivos para cargar archivos JSON con traducciones:

\n\n

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

\n\n

Cree un archivo de configuración 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

Estructura de los archivos de traducción

\n\n

Cree la carpeta public/locales con subcarpetas para cada idioma. Por ejemplo:

\n\n

\n
• public/locales/ru/translation.json
\n
• public/locales/en/translation.json
\n

\n\n

Ejemplo del contenido del archivo ru/translation.json:

\n\n

{\n  "greeting": "¡Hola, {{name}}!",\n  "items": "Tiene {{count}} mensaje",\n  "items_plural": "Tiene {{count}} mensajes",\n  "nested": {\n    "title": "Título",\n    "description": "Descripción"\n  }\n}

\n\n

Versión en 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

Tipado de traducciones en TypeScript

\n\n

Una de las principales ventajas de i18next es el tipado estricto. Cree un archivo 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

Ahora TypeScript verificará las claves de traducción en tiempo de compilación. Si intenta usar una clave inexistente, obtendrá un error.

\n\n

Uso en componentes React

\n\n

La biblioteca react-i18next proporciona el hook useTranslation y el 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: 'Iván' })}</h2>\n      <button onClick={() => changeLanguage('en')}>English</button>\n      <button onClick={() => changeLanguage('ru')}>Русский</button>\n    </div>\n  );\n}

\n\n

Pluralización e interpolación

\n\n

i18next admite reglas complejas de pluralización. En ruso hay tres formas (1, 2-4, 5+), en inglés dos. La biblioteca selecciona automáticamente la forma correcta según el número:

\n\n

// En el archivo de traducción (ru):\n{\n  "apple": "{{count}} manzana",\n  "apple_plural": "{{count}} manzanas",\n  "apple_plural_2": "{{count}} manzanas"\n}\n\n// Uso:\nconst