# node: Inicio rápido con Node.js
URL: https://generaltranslation.com/es/docs/node/tutorials/quickstart.mdx
---
title: Inicio rápido con Node.js
description: Agrega varios idiomas a tu servidor Node.js en menos de 10 minutos
---

Al final de esta guía, tu servidor Node.js responderá con contenido traducido según el idioma de la solicitud, usando cadenas en línea o registradas previamente.

**Requisitos previos:**

* Un servidor Node.js (Express, Fastify o similar)
* Node.js 18+

<Callout type="info">
  **¿Quieres una configuración automática?** Ejecuta `npx gt@latest` para configurar 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-node` es la biblioteca que gestiona las traducciones en tu servidor. `gt` es la herramienta de línea de comandos que prepara las traducciones para producción.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-node
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-node
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-node
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-node
    pnpm add --save-dev gt
    ```
  </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 le indica a la librería qué idiomas admites:

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

* **`defaultLocale`** — el idioma en el que están escritas las cadenas de tu servidor.
* **`locales`** — los idiomas a los que quieres traducir. Elige cualquiera de la [lista de configuraciones regionales compatibles](/docs/platform/supported-locales).

***


## Paso 3: Inicializa General Translation

Llama a **`initializeGT`** una sola vez al principio del archivo de entrada de tu servidor, antes de usar cualquier función de traducción:

```js title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Esto configura la biblioteca con tus idiomas admitidos y las credenciales del proyecto.

***


## Paso 4: Configura el contexto de configuración regional para cada solicitud

Cada solicitud debe saber qué idioma usar. Usa **`withGT`** para envolver los manejadores de solicitud de tus solicitudes: utiliza almacenamiento local asíncrono para que las funciones de traducción tomen automáticamente la configuración regional correcta:

```js title="server.js"
import { withGT } from 'gt-node';

app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});
```

***


## Paso 5: Traducir cadenas en línea

Para traducir cadenas directamente dentro de los manejadores de solicitudes, usa **`getGT`**:

```js title="server.js"
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({
    message: gt('Hello, world!'),
    welcome: gt('Welcome, {name}!', { name: 'Alice' }),
  });
});
```

`getGT` devuelve una función de traducción para la configuración regional de la solicitud actual.

***


## Paso 6: Registra previamente las cadenas constantes (opcional)

Para las cadenas definidas fuera de los manejadores de solicitud —como mensajes de error, etiquetas de enum o constantes—, usa **`msg`** para registrarlas en el ámbito del módulo y luego **`getMessages`** para resolver las traducciones en runtime:

```js title="messages.js"
import { msg } from 'gt-node';

export const GREETING = msg('Hello, world!');
export const WELCOME = msg('Welcome, {name}!');
export const NOT_FOUND = msg('Resource not found.');
```

```js title="handler.js"
import { getMessages } from 'gt-node';
import { GREETING, WELCOME, NOT_FOUND } from './messages.js';

app.get('/api/status', async (req, res) => {
  const m = await getMessages();
  res.json({
    greeting: m(GREETING),
    welcome: m(WELCOME, { name: 'Alice' }),
  });
});

app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});
```

Este patrón es útil cuando se usan las mismas cadenas en varios manejadores.

***


## Paso 7: 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 bajo demanda**: tu servidor 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 ejecutando:

```bash
npx gt auth
```

<Callout type="warn">
  Nunca expongas `GT_API_KEY` públicamente ni la subas al control de versiones.
</Callout>

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

    * Proporcionar manualmente tus propios archivos de traducción
    * Usar todas las funciones de traducción (`getGT`, `msg`, `getMessages`, etc.)
    * Ejecutar `npx gt generate` para crear plantillas de archivos de traducción y luego traducirlas tú mismo
  </Accordion>
</Accordions>

***


## Paso 8: Verlo en funcionamiento

Inicia tu servidor y pruébalo con distintos encabezados `Accept-Language`:

```bash
# Predeterminado (inglés)
curl http://localhost:3000/api/greeting

# Español
curl -H "Accept-Language: es" http://localhost:3000/api/greeting

# Francés
curl -H "Accept-Language: fr" http://localhost:3000/api/greeting
```

Deberías ver respuestas traducidas para cada idioma.

<Callout type="info">
  En desarrollo, las traducciones se generan bajo demanda; es posible que notes una breve demora la primera vez que se solicite un idioma nuevo. En producción, las traducciones se generan por adelantado y se cargan al instante.
</Callout>

***


## Paso 9: Ejemplo completo

Aquí tienes un servidor Express completo con todas las piezas juntas:

```js title="server.js"
import express from 'express';
import { initializeGT, withGT, getGT, msg, getMessages } from 'gt-node';

// Inicializar GT antes que cualquier otra cosa
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});

// Registrar previamente cadenas constantes
const NOT_FOUND = msg('Resource not found.');

const app = express();

// Establecer el contexto de configuración regional para cada solicitud
app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});

// Traducción en línea
app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, world!') });
});

// Traducción de mensajes registrados previamente
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

***


## Paso 10: Despliega a producción

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

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

Configura tus variables de entorno de **producción** en tu proveedor de alojamiento:

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

<Callout type="warn">
  Nunca expongas públicamente tu `GT_API_KEY`.
</Callout>

Eso es todo: tu servidor ya es multilingüe. 🎉

***


## Solución de problemas

<Accordions>
  <Accordion title="Las traducciones son lentas en desarrollo">
    Esto es de esperar. En desarrollo, las traducciones se realizan bajo demanda (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">
    Los textos ambiguos pueden dar lugar a traducciones inexactas. Por ejemplo, &quot;apple&quot; podría referirse a la fruta o a la empresa. Añade la opción `$context` para dar más contexto:

    ```js
    gt('Apple', { $context: 'the technology company' });
    ```

    Tanto `getGT()` como `msg()` admiten la opción `$context`.
  </Accordion>
</Accordions>

***

## Siguientes pasos

* [**`initializeGT`**](/docs/node/api/initialize-gt) — Opciones de configuración completas
* [**`withGT`**](/docs/node/api/with-gt) — Contexto de configuración regional para las solicitudes
* [**`getGT`**](/docs/node/api/get-gt) — Traducción de cadenas en línea
* [**`msg` &amp; `getMessages`**](/docs/node/api/get-messages) — Traducción de mensajes registrados previamente
* [**CLI**](/docs/cli/translate) — Referencia del flujo de trabajo de traducción