REST API & SDK de better-i18n: Gestión Programática de Traducciones

REST API & SDK de better-i18n: Gestión Programática de Traducciones

La plataforma better-i18n ofrece a los desarrolladores acceso programático completo a la gestión de traducciones — a través de un SDK de TypeScript, una REST API, herramientas CLI y un servidor MCP para asistentes de IA. Gestiona claves, traducciones, idiomas y contenido desde tu propio código y pipelines de CI.

Dos APIs, Propósitos Distintos

better-i18n expone dos APIs diferenciadas según lo que estés construyendo:

Ambas APIs utilizan cuerpos JSON en las solicitudes/respuestas y siguen convenciones REST.

Autenticación

Genera claves de API en Ajustes → API Keys en tu Dashboard.

# Translation API (gestión de claves, traducciones)
curl -H "Authorization: Bearer bi18_live_abc123..." \
  https://dash.better-i18n.com/api/...

# Content API (CMS headless)
curl -H "x-api-key: bi-your-api-key" \
  https://content.better-i18n.com/v1/content/acme/web-app/models

Nunca expongas claves de API en código del lado del cliente. Utiliza variables de entorno y proxies del lado del servidor.

Translation API

La Translation API gestiona el flujo de trabajo principal de i18n: proyectos, claves, traducciones e idiomas.

Proyectos

listProjects()          → Lista todos los proyectos a los que tienes acceso
getProject(project)     → Obtén detalles del proyecto, idiomas y namespaces

Cada proyecto se identifica con el formato org/project (p. ej., acme/web-app). Lo encontrarás en tu i18n.config.ts.

Claves de Traducción

listKeys(project, options)    → Busca y navega las claves de traducción
createKeys(project, keys)     → Crea claves con texto fuente y traducciones
updateKeys(project, updates)  → Actualiza traducciones para claves existentes
deleteKeys(project, keys)     → Elimina suavemente claves de traducción

Crea claves con traducciones en una sola llamada:

{
  "project": "acme/web-app",
  "keys": [
    {
      "name": "auth.login.title",
      "namespace": "auth",
      "sourceText": "Sign in to your account",
      "translations": {
        "tr": "Hesabınıza giriş yapın",
        "de": "Melden Sie sich bei Ihrem Konto an"
      }
    },
    {
      "name": "auth.login.button",
      "namespace": "auth",
      "sourceText": "Sign in"
    }
  ]
}

Busca y filtra claves:

{
  "project": "acme/web-app",
  "search": "login",
  "namespaces": ["auth"],
  "missingLanguage": "tr"
}

Actualiza traducciones con estado:

{
  "project": "acme/web-app",
  "translations": [
    {
      "key": "auth.login.title",
      "language": "tr",
      "text": "Hesabınıza giriş yapın",
      "status": "approved"
    }
  ]
}

Idiomas

addLanguage(project, language)   → Añade un nuevo idioma de destino
getProject(project)              → Consulta todos los idiomas activos y su progreso

Operaciones de Sync

getSyncs(project)    → Lista las operaciones de Sync recientes (GitHub, CDN, etc.)
getSync(project, id) → Obtén detalles de un trabajo de Sync específico

Content SDK

El @better-i18n/sdk es un cliente TypeScript para la Content API — nuestro CMS headless para contenido estructurado como posts de blog, entradas de changelog y páginas de marketing.

Instalación

npm install @better-i18n/sdk

Inicialización

import { createClient } from "@better-i18n/sdk";

const client = createClient({
  project: "acme/web-app",
  apiKey: process.env.BETTER_I18N_API_KEY!,
});

Query Builder (estilo Supabase)

El SDK proporciona un query builder encadenable e inmutable:

// Listar posts de blog publicados
const { data: posts, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published")
  .order("publishedAt", { ascending: false })
  .expand("author", "category")
  .limit(10);

// Obtener una entrada individual en francés
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("getting-started");

console.log(post.title, post.body);

Métodos Disponibles

Endpoints REST (Bajo el Capó)

El SDK llama a estos endpoints:

Herramientas CLI

El @better-i18n/cli se integra en tu flujo de trabajo de desarrollo:

# Detecta cadenas hardcodeadas en tu codebase
better-i18n scan

# Compara claves locales con el proyecto en la nube
better-i18n sync

# Integración CI/CD con salida JSON
better-i18n scan --ci --format json
better-i18n sync --format json

El CLI detecta automáticamente los hooks useTranslations() y getTranslations(), extrae namespaces y reporta traducciones faltantes — todo en menos de 100ms para codebases típicas.

Integración con Pre-commit y CI

# Hook pre-commit
npx @better-i18n/cli scan --staged --ci

# GitHub Actions
- run: npx @better-i18n/cli scan --ci --format json

Servidor MCP para Asistentes de IA

El servidor MCP (Model Context Protocol) de better-i18n permite que asistentes de IA como Claude, Cursor y Windsurf gestionen traducciones directamente desde tu IDE:

# Instalar servidor MCP
npm install @better-i18n/mcp

Los asistentes de IA pueden:

• Listar y buscar claves de traducción
• Crear nuevas claves con traducciones
• Actualizar traducciones existentes
• Verificar el estado del Sync
• Añadir nuevos idiomas

Esto significa que puedes decir «Añade traducciones al alemán para el namespace auth» y tu asistente de IA lo gestiona a través de la API.

Entrega vía CDN

Las traducciones se sirven globalmente a través de nuestro CDN con un patrón de URL predecible:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

Por ejemplo:

https://cdn.better-i18n.com/acme/web-app/de/common.json

Sin necesidad de Deploy — las traducciones se actualizan en el CDN automáticamente al publicarse.

SDKs de la Plataforma

Todos los paquetes están disponibles en npm y funcionan en cualquier runtime de JavaScript con fetch() nativo.

Recursos Relacionados

• Integración con Git — Sincroniza traducciones con tu repositorio mediante pull requests
• Webhooks & Eventos — Notificaciones en tiempo real para eventos de traducción
• Documentación Completa de la API — Referencia completa de endpoints