# react-native: Inicio rápido de React Native
URL: https://generaltranslation.com/es/docs/react-native/tutorials/quickstart.mdx
---
title: Inicio rápido de React Native
description: Agrega varios idiomas a tu aplicación de React Native en menos de 10 minutos
---

Al final de esta guía, tu aplicación de React Native mostrará contenido en varios idiomas y contará con un selector de idioma con el que tus usuarios podrán interactuar.

**Requisitos previos:**

* Una aplicación creada con React Native CLI (no Expo; consulta el [inicio rápido de Expo](/docs/react-native/tutorials/quickstart-expo) para proyectos con Expo)
* Node.js 18+

<Callout type="warn">
  `gt-react-native` sigue siendo experimental y puede que no funcione en todos los proyectos.
  Avísanos si encuentras algún problema [abriendo un issue en GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

<Callout type="info">
  **¿Quieres una configuración automática?** Ejecuta `npx gt@latest` para configurarlo todo con el [Asistente de configuración](/docs/cli/init). Esta guía explica la configuración manual.
</Callout>

***

## Paso 1: Instala los paquetes

`gt-react-native` es la biblioteca que gestiona las traducciones en tu aplicación. `gt` es la herramienta CLI que prepara las traducciones para producción.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react-native
    npm i -D gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react-native
    yarn add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react-native
    bun add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react-native
    pnpm add --save-dev gt
    cd ios && pod install
    ```
  </Tab>
</Tabs>

***

## Paso 2: Crea un archivo de configuración de traducción

Crea un archivo **`gt.config.json`** en la raíz de tu proyecto. Esto indica a la biblioteca qué idiomas admites:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "content/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — el idioma en el que está escrita tu aplicación (tu idioma de origen).
* **`locales`** — los idiomas a los que quieres traducir. Elige cualquiera de la [lista de configuraciones regionales compatibles](/docs/platform/supported-locales).
* **`files.gt.output`** — dónde el CLI guarda los archivos de traducción. `[locale]` se sustituye por cada código de idioma (por ejemplo, `content/es.json`).

***


## Paso 3: Configura los polyfills

El runtime de JavaScript de React Native no incluye las APIs de `Intl` que necesita `gt-react-native`. La forma más sencilla de solucionarlo es usar el plugin de Babel incluido.

Agrégalo a tu configuración de Babel y haz que `entryPointFilePath` apunte al archivo de entrada de tu app (consulta el campo `"main"` de tu `package.json`):

```js title="babel.config.js"
const path = require('path');
const gtPlugin = require('gt-react-native/plugin');
const gtConfig = require('./gt.config.json');

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    [
      gtPlugin,
      {
        locales: [gtConfig.defaultLocale, ...gtConfig.locales],
        entryPointFilePath: path.resolve(__dirname, 'App.tsx'),
      },
    ],
  ],
};
```

<Accordions>
  <Accordion title="¿El plugin de Babel no funciona? Agrega el polyfill manualmente">
    Instala los polyfills de FormatJS e impórtalos al inicio de tu archivo de entrada. Necesitas los polyfills base y datos específicos de la configuración regional para cada idioma que admitas.

    Consulta [la documentación de polyfills de FormatJS](https://formatjs.github.io/docs/polyfills) para ver la lista completa. Como mínimo, necesitas:

    ```tsx title="index.js"
    import '@formatjs/intl-getcanonicallocales/polyfill';
    import '@formatjs/intl-locale/polyfill';
    import '@formatjs/intl-pluralrules/polyfill-force';
    import '@formatjs/intl-numberformat/polyfill';
    import '@formatjs/intl-datetimeformat/polyfill';
    import '@formatjs/intl-datetimeformat/add-all-tz';

    // Agrega datos de configuración regional para cada idioma:
    import '@formatjs/intl-pluralrules/locale-data/en';
    import '@formatjs/intl-pluralrules/locale-data/es';
    import '@formatjs/intl-numberformat/locale-data/en';
    import '@formatjs/intl-numberformat/locale-data/es';
    // ... repite esto para cada configuración regional y polyfill
    ```
  </Accordion>
</Accordions>

***

## Paso 4: Crea un cargador de traducciones

Metro (el empaquetador de React Native) no admite importaciones dinámicas, así que debes asignar explícitamente cada configuración regional a su archivo de traducción:

```ts title="loadTranslations.ts"
const translations: Record<string, any> = {
  es: require("./content/es.json"),
  fr: require("./content/fr.json"),
  ja: require("./content/ja.json"),
};

export function loadTranslations(locale: string) {
  return translations[locale] ?? {};
}
```

La CLI genera estos archivos cuando ejecutas `npx gt translate`.

***


## Paso 5: Agrega GTProvider a tu aplicación

El componente **`GTProvider`** le da acceso a las traducciones a toda tu aplicación. Envuelve tu aplicación en la raíz:

```tsx title="App.tsx"
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
      projectId={process.env.GT_PROJECT_ID}
      devApiKey={process.env.GT_API_KEY}
    >
      {/* El contenido de tu app */}
    </GTProvider>
  );
}
```

`GTProvider` gestiona el estado de la configuración regional y pone las traducciones a disposición de todos los componentes hijos. La prop `devApiKey` habilita la traducción on-demand durante el desarrollo.

***


## Paso 6: Marca el contenido para su traducción

Envuelve cualquier texto que quieras traducir con el componente **`<T>`**:

```tsx title="screens/Home.tsx"
import { Text, View } from 'react-native';
import { T } from 'gt-react-native';

export default function Home() {
  return (
    <View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
      <T>
        <Text>This content will be translated automatically.</Text>
      </T>
    </View>
  );
}
```

Todo lo que está dentro de `<T>` se traduce como una sola unidad.

***


## Paso 7: Añade un selector de idioma

Usa el hook **`useLocaleSelector`** para crear un selector de idioma. A diferencia de `gt-react`, `gt-react-native` no exporta un componente `<LocaleSelector>` ya preparado; debes crear tu propia interfaz con el hook:

```tsx title="screens/Home.tsx"
import { Text, View, Pressable } from 'react-native';
import { T, useLocaleSelector } from 'gt-react-native';

export default function Home() {
  const { locales, locale, setLocale } = useLocaleSelector();

  return (
    <View>
      <View style={{ flexDirection: 'row', gap: 8, marginBottom: 16 }}>
        {locales.map((l) => (
          <Pressable key={l} onPress={() => setLocale(l)}>
            <Text style={{ fontWeight: l === locale ? 'bold' : 'normal' }}>{l}</Text>
          </Pressable>
        ))}
      </View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
    </View>
  );
}
```

`useLocaleSelector` devuelve las configuraciones regionales disponibles, la configuración regional actual y una función de actualización, lo que te da control total sobre la interfaz de usuario.

***

## Paso 8: Configura las variables de entorno (opcional)

Para ver las traducciones durante el desarrollo, necesitas claves de API de General Translation. Estas habilitan la **traducción on-demand**: tu app traduce el contenido en tiempo real mientras desarrollas.

Crea un archivo **`.env`**:

```bash title=".env"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

Obtén tus claves gratis en [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) o ejecuta:

```bash
npx gt auth
```

<Callout type="warn">
  Para desarrollo, usa una clave que empiece por `gtx-dev-`. Las claves de producción (`gtx-api-`) son solo para CI/CD.

  Nunca expongas claves de API de producción en el bundle de tu app ni las subas al control de versiones.
</Callout>

<Accordions>
  <Accordion title="¿Puedo usar gt-react-native sin claves de API?">
    Sí. Sin claves de API, `gt-react-native` funciona como una biblioteca de i18n estándar. No tendrás traducción on-demand durante el desarrollo, pero aun así puedes:

    * Proporcionar manualmente tus propios archivos de traducción
    * Usar todos los componentes (`<T>`, `<Var>`, `LocaleSelector`, etc.)
    * Ejecutar `npx gt generate` para crear plantillas de archivos de traducción y luego traducirlas tú mismo
  </Accordion>
</Accordions>

***


## Paso 9: Comprueba cómo funciona

Compila y ejecuta tu aplicación:

```bash
npx react-native run-ios
# o
npx react-native run-android
```

Usa el selector de idioma para cambiar de idioma. Deberías ver el contenido traducido.

<Callout type="info">
  En desarrollo, las traducciones se realizan on-demand; es posible que veas un breve estado de carga la primera vez que cambies a un idioma nuevo. En producción, las traducciones se generan con antelación y se cargan al instante.
</Callout>

***


## Paso 10: Traduce cadenas (no solo JSX)

Para cadenas de texto, como atributos `placeholder` o valores de `accessibilityLabel`, usa el **Hook `useGT`**:

```tsx title="screens/Contact.tsx"
import { TextInput, View } from 'react-native';
import { useGT } from 'gt-react-native';

export default function Contact() {
  const gt = useGT();

  return (
    <View>
      <TextInput
        placeholder={gt('Enter your email')}
        accessibilityLabel={gt('Email input field')}
      />
    </View>
  );
}
```

***


## Paso 11: Despliega en producción

En producción, las traducciones se generan de antemano en tiempo de construcción (sin llamadas a la API en tiempo real). Agrega el comando translate a tu script de compilación:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

Configura las variables de entorno de **producción** en tu CI/CD:

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

<Callout type="warn">
  Las claves de producción empiezan por `gtx-api-` (no `gtx-dev-`). Obtén una en [dash.generaltranslation.com](https://dash.generaltranslation.com). Nunca expongas claves de producción en el bundle de tu app.
</Callout>

Eso es todo: tu app ahora es multilingüe. 🎉

***


## Solución de problemas

<Accordions>
  <Accordion title="No se pudo encontrar 'GtReactNative'">
    ```
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found.]
    ```

    Esto significa que el módulo nativo no se ha enlazado. Ejecuta `cd ios && pod install` y vuelve a compilar la aplicación.
  </Accordion>

  <Accordion title="Error de códigos de configuración regional no válidos">
    ```
    Error: You are using invalid locale codes in your configuration.
    ```

    Normalmente, esto significa que los polyfills no están configurados correctamente. Asegúrate de que el plugin de Babel esté configurado (o de importar manualmente los polyfills) y borra la caché de Metro:

    ```bash
    npx react-native start --reset-cache
    ```
  </Accordion>

  <Accordion title="Las traducciones son lentas en desarrollo">
    Esto es normal. En desarrollo, las traducciones se hacen on-demand (tu contenido se traduce en tiempo real a través de la API). Esta demora **no existe en producción**: todas las traducciones se generan previamente con `npx gt translate`.
  </Accordion>

  <Accordion title="Algunas traducciones son inexactas">
    El texto ambiguo puede dar lugar a traducciones inexactas. Por ejemplo, &quot;apple&quot; podría referirse a la fruta o a la empresa. Agrega una prop `context` para ayudar:

    ```jsx
    <T context="the technology company">Apple</T>
    ```

    Tanto `<T>` como `useGT()` admiten la opción `context`.
  </Accordion>
</Accordions>

***

## Próximos pasos

* [**Guía del componente `<T>`**](/docs/react-native/guides/t) — Aprende sobre variables, plurales y patrones de traducción avanzados
* [**Guía de traducción de cadenas**](/docs/react-native/guides/strings) — Profundiza en `useGT`
* [**Componentes de variable**](/docs/react-native/guides/variables) — Maneja contenido dinámico con `<Var>`, `<Num>`, `<Currency>` y `<DateTime>`
* [**Despliegue en producción**](/docs/react-native/tutorials/quickdeploy) — Configuración de CI/CD, almacenamiento en caché y optimización del rendimiento