Traducción de cadenas

Descripción general

Esta guía te mostrará cómo internacionalizar cadenas de texto en tu aplicación Next.js usando el hook useGT() y la función getGT().

Cubriremos lo siguiente:

Cuándo usar el hook useGT()

Cómo usar el hook useGT()

Usando variables

Ejemplos

Errores comunes

En esta guía, cuando nos referimos al hook useGT(), también nos referimos a la función getGT().

La única diferencia entre ambos es cuándo usarlos.

La función getGT() es una función asíncrona que devuelve una función prometida, mientras que el hook useGT() devuelve la función directamente.

Usa la función getGT() en componentes síncronos, y el hook useGT() en componentes asíncronos.

src/app/page.tsx

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

src/app/page.tsx

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  const translatedString = translate('Hello, world!');
  return <div>{translatedString}</div>;
}

Cuándo usar el hook `useGT()`

El hook useGT() es un hook de React que se puede usar para traducir cadenas de texto.

En la mayoría de los casos, puedes usar el componente <T>. Sin embargo, en casos donde JSX no es apropiado, se puede utilizar el hook useGT().

Algunos casos en los que el hook useGT() podría ser más apropiado son:

En propiedades que esperan estrictamente cadenas de texto, como los atributos placeholder o title.
Cuando la cadena de texto es parte de un objeto más grande, por ejemplo:

const user = {
  title: 'Mr.',
  name: 'John',
  description: 'John is a software engineer at General Translation',
}

Aquí, solo la propiedad description debe ser traducida.

Siempre que sea posible, deberías usar el componente <T>. El componente <T> te permite traducir contenido JSX, y es la forma recomendada de traducir cadenas de texto.

Cómo usar el hook `useGT()`

El hook useGT() debe ser llamado dentro del <GTProvider>.

Para traducir una cadena de texto, simplemente pasa la cadena directamente a la función devuelta por el hook.

import { useGT } from 'gt-next';
export function MyComponent() {
  const translate = useGT();
  return <div>{translate('Hello, world!')}</div>;
}

A diferencia de las bibliotecas i18n tradicionales, el hook useGT() no requiere que pases una key a la función. En su lugar, la cadena se pasa directamente a la función.

¡Esto significa que no necesitas usar diccionarios!

Cómo usar la función `getGT()`

Por otro lado, dado que la función getGT() es una función asíncrona, puede ser utilizada en componentes async, y no necesita ser llamada dentro del <GTProvider>.

El contexto para getGT() es manejado por la función withGTConfig en tu archivo next.config.ts.

import { getGT } from 'gt-next/server';
export async function MyComponent() {
  const translate = await getGT();
  return <div>{translate('Hello, world!')}</div>;
}

Usando variables

A menudo, necesitarás traducir cadenas que contienen variables.

Por ejemplo, puedes necesitar traducir una cadena que contiene valores numéricos.

Para agregar variables, simplemente añade la variable a la cadena como un marcador de posición con {variable}, y pasa un objeto como segundo argumento a la función devuelta por el hook.

const price = 100;
const translate = useGT();
translate('There are {count} items in the cart', { count: 10 });

El marcador de posición {count} será reemplazado con el valor de la variable count.

Esto te permite mostrar valores dinámicos en tus traducciones.

Para más información sobre la API, consulta la referencia de la API.

gt-next soporta el formato de mensaje ICU, que te permite también formatear tus variables.

const price = 100;
const translate = useGT();
translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });

El formato de mensaje ICU es una forma poderosa de formatear tus variables. Para más información, consulta la documentación del formato de mensaje ICU.

Ejemplos

Traduciendo una cadena en un componente

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  return (
    <div>
      <h1>{t('Hello, world!')}</h1>
    </div>
  )
}

export default function MyComponent() {
  return (
    <div>
      <h1>Hello, world!</h1>
    </div>
  )
}

Traduciendo una cadena con variables

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const count = 10;
  return (
    <div>
      <h1>{t('There are {count} items in the cart', { count })}</h1>
    </div>
  )
}

export default function MyComponent() {
  const count = 10;
  return (
    <div>
      <h1>There are {count} items in the cart</h1>
    </div>
  )
}

Traduciendo partes de un objeto

import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const users = [
    {
      name: 'John',
      description: t('John is a software engineer at General Translation'),
    },
    {
      name: 'Jane',
      description: t('Jane is a software engineer at Google'),
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

export default function MyComponent() {
  const users = [
    {
      name: 'John',
      description: 'John is a software engineer at General Translation',
    },
    {
      name: 'Jane',
      description: 'Jane is a software engineer at Google',
    },
  ]
  return (
    <div>
      {users.map((user) => (
        <div key={user.name}>
          <h1>{user.name}</h1>
          <p>{user.description}</p>
        </div>
      ))}
    </div>
  )
}

Traduciendo constantes compartidas

src/llms.ts

// Custom function to get LLM data with translations
export function getLLMData(t: (content: string) => string) {
  return [
    {
      name: 'GPT-4.1',
      id: 'gpt-4.1',
      description: t('GPT-4.1 is a large language model developed by OpenAI'),
    },
    {
      name: 'Claude 3.7 Sonnet',
      id: 'claude-3-7-sonnet',
      description: t('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
    },
  ]
}

import { getLLMData } from './llms';
import { useGT } from 'gt-next';

export default function MyComponent() {
  const t = useGT();
  const llms = getLLMData(t);
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

src/llms.ts

export const llms = [
  {
    name: 'GPT-4.1',
    id: 'gpt-4.1',
    description: 'GPT-4.1 is a large language model developed by OpenAI',
  },
  {
    name: 'Claude 3.7 Sonnet',
    id: 'claude-3-7-sonnet',
    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
  },
]

import { llms } from './llms';

export default function MyComponent() {
  return (
    <div>
      {llms.map((llm) => (
        <div key={llm.id}>
          <h1>{llm.name}</h1>
          <p>{llm.description}</p>
        </div>
      ))}
    </div>
  )
}

En este último ejemplo, convertimos el array llms en una función que devuelve los datos con traducciones. Pasamos la función t a la función que devuelve los datos.

Alternativamente, también podrías convertir el array llms en un hook personalizado. Sin embargo, esto no se recomienda, ya que necesitarás ser muy cuidadoso sobre cómo usas el hook useGT(), para no violar las reglas de React.

Errores Comunes

Traducción de Contenido Dinámico

Todas las cadenas deben ser conocidas en tiempo de compilación.

Esto significa que no puedes traducir contenido dinámico que se genera o recupera en tiempo de ejecución.

Esto incluye variables, incluso si son cadenas.

export default function MyComponent() {
  const [dynamicContent, setDynamicContent] = useState('Hello, world!');
  const t = useGT();
  return (
    <div>
      <h1>{t(dynamicContent)}</h1> {/* This will not work */}
    </div>
  )
}

La herramienta CLI te advertirá si intentas traducir contenido dinámico con el hook useGT().

Próximos pasos

Aprende cómo traducir contenido JSX bajo demanda.
Obtén más información sobre el componente <T>.
Consulta la referencia de la API para useGT().

Traducción de cadenas

¿Por qué no puedo importar directamente el array `llms`?

¿Qué hago si necesito traducir contenido dinámico?

En esta página