Guía rápida · Node.js

Objetivo: un servicio Node sirviendo textos traducidos, en menos de diez minutos. Lee la primera sección antes de escribir código: el cliente hace menos de lo que sugiere su nombre, y saberlo de entrada te ahorra una hora.

Qué hace el cliente

azbox-node expone exactamente una clase con un método:

new AzboxClient({ token, projectId, language })
await client.getKeywords({ afterUpdatedAt? })

Tres consecuencias:

• 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 helper translate(). Recibes la lista y construyes el índice tú. De eso van los pasos 4 y 5.

La credencial es token, no apiKey. Pasar apiKey lanza AzboxClient: 'token' is required.

Antes de empezar

• Node 18 o superior — el cliente usa el fetch global
• Un proyecto de AZbox con su Project ID y su API key

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

3 · Trae las keywords

import { AzboxClient } from "azbox-node";

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

const keywords = await client.getKeywords();
// [{ id: "home.title", data: { translation: "Bienvenido", ... } }]

Una sola llamada a GET /v1/projects/:id/keywords?token=…&language=….

4 · Construye el índice

Llamar a getKeywords() por cada texto sería una petición HTTP por texto. Tráelo una vez al arrancar:

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

export async function loadLanguage(language: string) {
  const client = new AzboxClient({
    token: process.env.AZBOX_API_KEY!,
    projectId: process.env.AZBOX_PROJECT_ID!,
    language,
  });
  const keywords = await client.getKeywords();
  dictionaries.set(language, new Map(
    keywords
      .filter((k) => typeof k.data.translation === "string")
      .map((k) => [k.id, k.data.translation as string]),
  ));
}

export function t(language: string, key: string, params?: Record<string, string | number>) {
  const value = dictionaries.get(language)?.get(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.getKeywords({ afterUpdatedAt: lastSync });

Esto es lo que hace posible el OTA en servidor: corriges un texto en el panel y el siguiente refresco lo recoge sin desplegar. 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 algo falla

• 'token' is required — has pasado apiKey. La opción es token.
• Array vacío — el proyecto no tiene keywords en ese idioma, o el código de idioma no coincide con el configurado.
• fetch is not defined — Node anterior a la 18.

Siguiente

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