Traducción de cadenas

Descripción general

Esta guía te llevará paso a paso por el proceso de internacionalizar cadenas 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()

Uso de 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 del lado del servidor que retorna una función prometida, mientras que el hook useGT() retorna la función directamente.

Usa la función getGT() en componentes de servidor, y el hook useGT() en componentes de cliente.

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>;
}

src/app/page.tsx

'use client';
import { useGT } from 'gt-next/client';
export function MyComponent() {
  const translate = useGT();
  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 de <GTProvider>.

Para traducir una cadena, simplemente pasa la cadena directamente a la función que retorna el hook.

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

A diferencia de las bibliotecas tradicionales de i18n, 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 del lado del servidor, puede usarse en componentes de servidor y no necesita ser llamada dentro de <GTProvider>.

El contexto para getGT() es gestionado 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>;
}

Uso de variables

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

Por ejemplo, puede que necesites traducir una cadena que contenga 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 que retorna el hook.

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

El marcador de posición {count} será reemplazado por 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.

Ejemplos

Traduciendo una cadena en un componente

import { useGT } from 'gt-next/client';

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/client';

export default function MyComponent() {
  const t = useGT();
  const count = 10;
  return (
    <div>
      <h1>{t('There are {count} items in the cart', { variables: { 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/client';

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

import { useGT } from 'gt-next/client';
// Custom hook to get LLM data with translations
export function useLLMData() {
  const t = useGT();
  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 { useLLMData } from './llms';

export default function MyComponent() {
  const llms = useLLMData();
  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>
  )
}

¡Ten cuidado! En este último ejemplo, debes tener mucho cuidado con cómo usas el hook useGT(). Asegúrate de que no viole las reglas de React.

Además, asegúrate de que el hook useGT() se llame dentro del contexto de React. Si tus constantes están definidas fuera de un componente de React, probablemente necesitarás crear un hook personalizado para acceder a tus datos con traducciones.

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