Guía rápida · Node.js

Objetivo: un servicio Node sirviendo textos traducidos, en menos de diez minutos.

Usa azbox-node 0.2.0 o superior. La 0.1.0 y la 0.1.1 nunca funcionaron contra la API. Si tienes una de ellas, basta con npm install azbox-node@latest: la clase y los métodos son los mismos.

Qué hace el cliente

azbox-node es una clase:

const client = new AzboxClient({ apiKey, projectId, language })
await client.getTranslations({ afterUpdatedAt? }) // { "home.title": "Bienvenido", … }
await client.getKeywords({ afterUpdatedAt? })     // la respuesta tal cual de la API

Tres cosas que conviene saber:

• Solo lee. Las keywords se crean en el panel; no hay método de subida.
• Un idioma por cliente. Para varios idiomas, un cliente para cada uno.
• No hay función t(). Recibes el diccionario y buscas los textos tú. De eso va el paso 4.

Antes de empezar

• Node 18 o superior — el cliente usa el fetch global
• Un proyecto de AZbox con su Project ID y una API key (panel → Settings → API keys)

1 · Crea el proyecto e importa tus textos

En el panel: Create Project y luego importa tu en.json (el formato i18next se lee de forma nativa, claves anidadas incluidas) o añade keywords con Add Keyword.

2 · Instala

npm install azbox-node

Funciona con import y con require.

3 · Trae las traducciones

import { AzboxClient } from "azbox-node";

const client = new AzboxClient({
  apiKey: process.env.AZBOX_API_KEY,
  projectId: process.env.AZBOX_PROJECT_ID,
  language: "ES",
});

const translations = await client.getTranslations();
// { "home.title": "Bienvenido", … }

Una sola llamada a GET /v1/projects/:id/keywords. Las keywords que aún no tienen texto en ese idioma se quedan fuera. Si necesitas todo lo que devuelve la API, getKeywords() te da [{ id, data: { keyword, translation, … } }]; la clave es data.keyword, y el id es un identificador interno.

4 · Construye el índice

Llamar a la API por cada texto sería una petición HTTP por texto. Cárgalo una vez al arrancar:

import { AzboxClient } from "azbox-node";

const dictionaries = new Map<string, Record<string, string>>();

export async function loadLanguage(language: string) {
  const client = new AzboxClient({
    apiKey: process.env.AZBOX_API_KEY!,
    projectId: process.env.AZBOX_PROJECT_ID!,
    language,
  });
  dictionaries.set(language, await client.getTranslations());
}

export function t(language: string, key: string, params?: Record<string, string | number>) {
  const value = dictionaries.get(language)?.[key];
  if (value === undefined) return key;
  return params
    ? value.replace(/\{(\w+)\}/g, (m, p) => String(params[p] ?? m))
    : value;
}

La interpolación es cosa tuya: la API devuelve la cadena tal como está guardada, con sus placeholders.

5 · Refresca solo lo que cambió

const changed = await client.getTranslations({ afterUpdatedAt: lastSync });
dictionaries.set("ES", { ...dictionaries.get("ES"), ...changed });

Esto es lo que hace posible el OTA en servidor: corriges un texto en el panel y el siguiente refresco lo recoge sin desplegar. Guarda la hora de la última respuesta que aplicaste, no la hora actual. Un refresco fallido no es fatal: sigues teniendo el diccionario anterior en memoria.

6 · En CI

env:
  AZBOX_API_KEY: ${{ secrets.AZBOX_API_KEY }}
  AZBOX_PROJECT_ID: ${{ secrets.AZBOX_PROJECT_ID }}

Si en CI solo necesitas escribir los ficheros de traducción en disco, el CLI lo hace sin escribir código.

Si algo falla

Los errores se lanzan como AzboxError, con status y el detail de la API.

• 401 — la API key es incorrecta o está revocada. Crea otra en el panel.
• 403 — la clave no tiene acceso a ese proyecto, o está atada a otro.
• Un diccionario vacío — o el proyecto aún no tiene keywords (getKeywords() devuelve []), o el código de idioma no es uno de los del proyecto. Un código desconocido no da error: todas las keywords llegan sin traducción. Revisa los códigos en los ajustes del proyecto.
• fetch is not available — Node anterior a la 18.

Siguiente

• Referencia de JSON / i18next
• Guía de Next.js
• Referencia de la API REST