Migrando a gt-next

Visión general

Esta guía te llevará a través del proceso de internacionalización de tu aplicación Next.js existente utilizando gt-next como una biblioteca i18n independiente. Esta guía también puede ser utilizada para ayudarte a migrar desde otra biblioteca i18n a gt-next.

Todas las traducciones se almacenan en el repositorio de tu proyecto y son gestionadas por ti. Además, tú aportas tus propias traducciones. Esto significa que no tendrás que añadir claves de API.

Si deseas generar automáticamente traducciones para tus archivos JSON, consulta la herramienta CLI.

Cómo funciona

Las traducciones pueden residir en archivos JSON llamados "diccionarios" (en.json, fr.json, etc.). Las claves se utilizan como referencias, y los valores son el contenido traducido:

public/dictionaries/en.json

{
  "greeting": "Hello, World!",
}

public/dictionaries/fr.json

{
  "greeting": "Bonjour, le monde!",
}

Las traducciones se referencian en tu aplicación con el hook useDict() y la función getDict():

components/MyComponent.js

import { useDict } from 'gt-next/client';
import { getDict } from 'gt-next/server';
 
export default function MyComponent() {
  const d = useDict(); // client-side
  const d = await getDict(); // server-side
  return (
    <div>
      <h1>{d('greeting')}</h1>
    </div>
  );
}

Nota: Debido a que estas traducciones son gestionadas por ti, necesitarás actualizarlas manualmente a medida que tu aplicación evolucione. Eso significa que cada vez que añadas o cambies contenido, tendrás que actualizar tus archivos de traducción.

Considera usar la herramienta CLI si estás interesado en automatizar este proceso.

Configuración

1. Habilitar traducciones

Utiliza el plugin withGTConfig() para configurar el comportamiento i18n de tu aplicación Next.js.

next.config.js

import { withGTConfig } from 'gt-next';
 
const nextConfig = {
  // Tu configuración de Next.js
};
 
export default withGTConfig(nextConfig, {
  locales: ['en', 'fr'], // Idiomas soportados (Inglés, Francés)
});

2. Añadir el archivo cargador de diccionario

Este loadDictionary() es responsable de cargar tus traducciones. Todas las traducciones se almacenan en archivos JSON anidados llamados diccionarios.

Aquí, especificamos que nuestros archivos de traducción están almacenados en el directorio /public/dictionaries/.

src/loadDictionary.js

export default async function loadDictionary(locale) {
  const t = await import(`../public/dictionaries/${locale}.json`);
  return t.default;
}

3. Envuelve tu aplicación en un `<GTProvider>`

Envuelve tu aplicación en un <GTProvider> para habilitar el contexto de traducción. Esto te permite acceder a las traducciones en componentes del lado del cliente.

layout.js

import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

4. Crea tus archivos de traducción

Tus archivos de traducción deben almacenarse en el directorio ./public/dictionaries. Cada archivo debe nombrarse según el idioma que representa, por ejemplo, en.json, fr.json, etc.

public/dictionaries/en.json

{
  "greeting": "Hello, World!",
}

Luego añade los correspondientes archivos de traducción del diccionario en francés:

public/dictionaries/fr.json

{
  "greeting": "Bonjour, le monde!",
}

5. ¡Usa tus traducciones!

Ahora puedes acceder a tus traducciones con useDict() y getDict().

components/MyComponent.js

import { useDict } from 'gt-next/client';
import { getDict } from 'gt-next/server';
 
export default function MyComponent() {
  const d = useDict(); // del lado del cliente
  const d = await getDict(); // del lado del servidor
  return (
    <div>
     {/* en: "Hello, World!"  fr: "Bonjour, le monde!" */}
      <h1>{d('greeting')}</h1> // [!code highlight]
    </div>
  );
}

Consejo: Para más información sobre la sintaxis del diccionario, como insertar variables, consulta la referencia del diccionario.

Compatibilidad

Esta guía te ayuda a migrar desde otra biblioteca de i18n a gt-next. El formato del diccionario es generalmente compatible con otras bibliotecas.

Nuestros diccionarios soportan variables, fechas e interpolación de números. Consulta las opciones del diccionario para más información.

Sin embargo, si tu proyecto está utilizando sintaxis compleja como plurales o ramas, necesitarás convertirlos a la sintaxis de gt-next.

Consulta la página de Componentes de Ramas para más información sobre la sintaxis de gt-next.

Notas

Usa gt-next para gestionar manualmente las traducciones en tu proyecto.
Las traducciones se almacenan en archivos JSON llamados "diccionarios" (en.json, fr.json, etc.).
Usa useDict() y getDict() para acceder a tus traducciones.

Próximos pasos

Para obtener más información sobre la sintaxis del diccionario, consulte la referencia del diccionario.
Considere usar el comando translate si está interesado en automatizar el proceso de traducción.

Migrando a gt-next

En esta página