Pon a traducir el contenido de tu app de React en minutos.

Requisitos previos: React, conocimientos básicos de JavaScript

Instalación

Instala los paquetes gt-react y gtx-cli:

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

Configuración

GTProvider

El componente GTProvider proporciona contexto de traducción a tus componentes de React. Administra el estado del locale, las traducciones y habilita los hooks useGT y useTranslations.

Agrega el GTProvider al componente raíz de tu aplicación:

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <YourAppContent />
    </GTProvider>
  );
}

Crea un archivo gt.config.json en la raíz de tu proyecto:

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Personaliza las locales de tu proyecto. Consulta las locales compatibles para ver las options.

Variables de entorno

Añade a tu archivo de entorno para la recarga en caliente durante el desarrollo:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

Obtén tus claves de API gratuitas en dash.generaltranslation.com o ejecuta:

npx gtx-cli auth

Uso

Ahora puedes empezar a internacionalizar tu contenido. Hay dos enfoques principales:

Contenido JSX con <T>

Envuelve elementos JSX para traducirlos con el componente <T>:

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>¡Bienvenido a nuestra app!</h1>
    </T>
  );
}

Para contenido dinámico, utiliza componentes de variables como <Var>:

import { T, Var } from 'gt-react';

function Greeting({ user }) {
  return (
    <T>
      <p>¡Hola, <Var>{user.name}</Var>!</p>
    </T>
  );
}

Consulta la guía sobre el uso del componente <T> para obtener más información.

Cadenas de texto simples con useGT

Para atributos, etiquetas y texto sin formato con el hook useGT:

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Introduce tu correo electrónico')}
      aria-label={t('Campo de entrada de correo electrónico')}
    />
  );
}

Consulta la guía sobre traducción de cadenas para obtener más información.

Prueba tu app

Prueba tus traducciones cambiando el idioma:

1. Agrega un menú desplegable para seleccionar el locale usando <LocaleSelector>:

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. Inicia tu servidor de desarrollo:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Visita localhost:3000 y cambia el idioma desde el menú desplegable de selección de locale.

En desarrollo, las traducciones se cargan bajo demanda (verás una breve carga). En producción, todo está pretraducido.

Solución de problemas

Implementación

En producción, debes pretraducir el contenido porque la traducción en tiempo de ejecución está deshabilitada (excepto para los componentes/funciones <Tx> y tx).

1. Obtén una clave de API de producción en dash.generaltranslation.com.

   Las claves de producción comienzan con gtx-api- (a diferencia de las claves de desarrollo, que comienzan con gtx-dev-). Más información sobre las diferencias entre entornos.

2. Agrégala a tu entorno de CI/CD:

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   Nunca antepongas a las claves de producción el prefijo de variables públicas de tu framework (como VITE_, REACT_APP_, etc.); deben permanecer solo del lado del servidor.

3. Ejecuta el comando translate para traducir tu contenido:

   npx gtx-cli translate

   Puedes configurar el comportamiento del comando translate con el archivo gt.config.json.

   Consulta la guía de referencia de la herramienta CLI para obtener más información.

4. Actualiza tu script de build para traducir antes de compilar:

   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }

Próximos pasos

• Guía del componente <T> - Análisis detallado del componente <T> y de la traducción en JSX
• Guía de traducción de cadenas - Uso de useGT para traducir cadenas
• Componentes de variables - Gestiona contenido dinámico con <Var>, <Num>, etc.