para desarrolladores

La localización como un paso de la canalización.

Envuelve una cadena en _(), completa cada configuración regional con un comando y edita cualquier traducción en tiempo real en tu aplicación en ejecución: archivos .po de principio a fin, escritos directamente en tu repositorio. O gestiona todo tú mismo con una API HTTP real.

Obtener una clave de APIExplorar las herramientas
herramientas de desarrollo y compilación

Herramientas de compilación para JavaScript y TypeScript.

Cuatro paquetes npm llevan a Echo Lingua desde una cadena marcada hasta una traducción enviada, sin salir de su base de código: el tiempo de ejecución @echo-lingua/i18n, extraer y compilar con @echo-lingua/i18n-cli, completar cada localización con @echo-lingua/sdk, y editar en vivo en el navegador con @echo-lingua/inline-editor. El mismo @echo-lingua/i18n-cli también maneja PHP y Laravel; vea herramientas de compilación para cada plataforma a continuación.

@echo-lingua/i18n

Envuelva las cadenas en _(); el i18n-cli extrae un .po por localización y compila un tiempo de ejecución diminuto.

Extraer y compilar →

@echo-lingua/sdk

Completa cada configuración regional a través de la API, desde la CLI o un cliente tipado.

Traducir →

@echo-lingua/inline-editor

Una barra de herramientas solo para desarrollo para editar traducciones en la aplicación en ejecución.

Editar en el navegador →
extraer y compilar

Envuelve una cadena. Envía un pequeño entorno de ejecución.

Envuelva el texto de la interfaz en _() desde el tiempo de ejecución @echo-lingua/i18n; la herramienta @echo-lingua/i18n-cli escanea su código fuente, hidrata un .po por localización y compila los traducidos en un tiempo de ejecución compacto con marcadores de posición, plurales y texto enriquecido. Añada un contexto, flags o una nota al modelo directamente en el sitio de la llamada. El tiempo de ejecución es opcional y solo para JS; la CLI es la mitad agnóstica al proyecto.

@echo-lingua/i18n en npm@echo-lingua/i18n-cli en npm
marca cadenas, añade banderas cuando las necesites
import { _, EL } from '@echo-lingua/i18n';

_('Save changes');
_('Hello {name}', { name });
_('You have {count} item', 'You have {count} items', { count });

// La cola de opciones: banderas, un msgctxt y una nota para el modelo.
_('Order', {}, { context: 'verb' });
_('Save', {}, { flags: [EL.CONTEXT_UI_LABEL] });
_('There is a file', 'There are {count} files', { count }, {
  flags: [EL.QUALITY_PRO, EL.CONTEXT_LEGAL],
  comment: 'Shown under the section title',
});
extraer → compilar
# El tiempo de ejecución para su aplicación, la cadena de herramientas para su compilación
npm i @echo-lingua/i18n
npm i -D @echo-lingua/i18n-cli

# Analiza el código e hidrata un .po por configuración regional
npx echo-lingua-i18n extract

# Compilar los catálogos traducidos en el entorno de ejecución
npx echo-lingua-i18n compile
más allá de javascript

Herramientas de compilación para cada plataforma.

El extractor y compilador, @echo-lingua/i18n-cli, es agnóstico al proyecto. Escanea JavaScript, TypeScript y PHP (incluyendo plantillas .phtml), hidrata los mismos archivos .po y los compila a lo que sea que su entorno de ejecución lea de forma nativa: el catálogo JS, un .mo binario para PHP gettext(), o JSON plano para Laravel __(). No hay un tiempo de ejecución de Echo Lingua que adoptar fuera de JS; usted mantiene el suyo. Cualquier otra pila de gettext (Python, Go, C) impulsa la misma plataforma a través de la API HTTP a continuación.

@echo-lingua/i18n-cli en npm
marcar cadenas en PHP o .phtml
<?php
// Marcar cadenas con las funciones de gettext / Laravel que ya utiliza
_('Account settings');
ngettext('one invoice', '{count} invoices', $n);
pgettext('nav', 'Home');
__('Welcome back');   // clave de cadena de Laravel
compilar objetivos nativos
// i18n.config.mjs — una configuración para toda la cadena de herramientas
export default {
  locales: ['de', 'fr'],
  include: ['src/**/*.{php,phtml}'],
  compileTargets: ['mo'],   // o ’laravel’ (JSON plano), o ’js’
};

# Escribe un .mo nativo por localización para PHP gettext()
npx echo-lingua-i18n sync
completar cada configuración regional

Traduce desde la CLI o desde tu propio código.

El cliente de la API y la CLI de traducción. echo-lingua translate lee tu configuración, completa el .po de cada configuración regional a través de la API y los escribe de vuelta. O llama al cliente tipado desde tu propio código: crea un trabajo, espera a que termine y descarga el resultado con la estructura del repositorio.

@echo-lingua/sdk en npm
la CLI de traducción
# Completa el .po de cada configuración regional a través de la API, en el lugar
npm i @echo-lingua/sdk

# Lee tu configuración y vuelve a escribir las traducciones
npx echo-lingua translate
o el cliente tipado
import { EchoLingua } from '@echo-lingua/sdk';

const el = new EchoLingua({ apiKey: process.env.ECHO_LINGUA_KEY });

// Crea un trabajo, espera a que termine y descarga el archivo zip con la estructura del repositorio.
const job = await el.createJob({
  sourceLanguage: 'en',
  contextMode: 'ui-label',
  quality: 'standard',
  inputs: [{ filename: 'de/messages.po', targetLanguage: 'de', content }],
});
const done = await el.waitForJob(job.id, { onProgress: (j) => log(j.status) });
const zip = await el.downloadJob(done.id);
editar en el navegador

Edita las traducciones en la aplicación en ejecución.

Una barra de herramientas solo para desarrollo se integra en tu aplicación. Mantén pulsado Alt y haz clic en cualquier cadena traducida para editar su traducción en tiempo real, corregir el origen en inglés, añadir contexto o indicadores, o dejar que la IA corrija, acorte o vuelva a traducir. Gestiona formas plurales, sobrescribe el inglés mostrado y ejecuta todo el bucle de extracción → traducción → compilación; cada cambio se escribe directamente en tu repositorio.

@echo-lingua/inline-editor en npm
añadir el plugin de Vite (solo desarrollo)
// vite.config.ts — dev only
import { echoLinguaBabel, echoLinguaInlineEditor } from '@echo-lingua/inline-editor';

export default defineConfig(({ command }) => ({
  plugins: [
    react(command === 'serve' ? { babel: { plugins: [echoLinguaBabel()] } } : {}),
    echoLinguaInlineEditor(),
  ],
}));

@echo-lingua/inline-editor

El editor en el navegador. Se vincula con @echo-lingua/i18n: una transformación de Babel asigna cada clic a la llamada _() exacta, y un servidor de desarrollo lee y escribe tus archivos .po y el código fuente. Nunca se envía a producción.

la API HTTP

O configúralo tú mismo.

¿No usas JavaScript o estás automatizando desde otra plataforma? Todas las funciones anteriores son llamadas HTTP simples: una clave con ámbito, un POST y un webhook firmado cuando termine. Funciona con cualquier proyecto gettext, en cualquier lenguaje.

Estimar y crear

Prueba el coste gratis y luego envía el trabajo mediante POST.

Inicio rápido →

Webhooks firmados

Entrega firmada con HMAC en el momento en que se completa un trabajo.

Webhooks →

Referencia completa

Todos los endpoints, ámbitos y payloads.

Referencia →
inicio rápido

Estima el coste y luego crea el trabajo.

Comprueba primero el tamaño y el coste con /v1/jobs/estimate (no se cobra nada) y luego crea la ejecución con el mismo cuerpo. Cada entrada de inputs es un archivo .po con su propio targetLanguage; sourceLanguage y contextMode son obligatorios, quality es draft, standard o pro.

POST /v1/jobs/estimate
curl -X POST https://api.echo-lingua.com/v1/jobs/estimate \
  -H "Authorization: Bearer $ECHO_LINGUA_KEY" \
  -H "Content-Type: application/json" \
  -d @job.json   # same body as the create call — nothing is charged
200 · tamaño + coste, no se cobra nada
{
  "entries": 550,
  "chunks": 10,
  "words": 7400,
  "chargedMicros": 2386500,
  "creditRequiredMicros": 2505825
}
POST /v1/jobs
curl -X POST https://api.echo-lingua.com/v1/jobs \
  -H "Authorization: Bearer $ECHO_LINGUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLanguage": "en",
    "contextMode": "ui-label",
    "quality": "standard",
    "inputs": [
      { "filename": "de/messages.po", "targetLanguage": "de", "content": "…" },
      { "filename": "ar/messages.po", "targetLanguage": "ar", "content": "…" }
    ]
  }'
201 · el trabajo creado
{
  "id": "job_8f2c41",
  "status": "QUEUED",
  "sourceLanguage": "en",
  "contextMode": "ui-label",
  "quality": "standard",
  "createdAt": 1726669120000
}
autenticación y claves con ámbito

Un token de portador. Los ámbitos que le concedas.

Crea claves en la aplicación; cada una se muestra once, incluye una fecha de caducidad y se puede revocar. El uso se atribuye por clave. Autentícate con una sola cabecera:

cada solicitud
Authorization: Bearer elk_live_2b7f…
# elk_-prefixed. Se muestra una vez al crearlo, guárdalo en un secreto.

translate:write

Crea trabajos, reintenta entradas fallidas y cancela ejecuciones.

jobs:read

Consulta el estado y recuentos de los trabajos, lista los trabajos y descarga los resultados.

webhooks

Entrega firmada, sin sondeos.

Registra un punto de conexión para job.completed y job.failed. Cada entrega incluye una firma HMAC-SHA256 del cuerpo sin procesar; verifícala antes de confiar en ella. Los reintentos utilizan un retroceso exponencial acotado.

entrega · cabeceras y cuerpo
POST https://your-app.example/hooks/echo-lingua
X-EchoLingua-Signature: 9f86d0818… (hex HMAC-SHA256 del cuerpo sin procesar)
X-EchoLingua-Timestamp: 1726669123456
X-EchoLingua-Delivery: whd_3f9c8a

{
  "id": "whd_3f9c8a",
  "type": "job.completed",
  "createdAt": 1726669123456,
  "data": {
    "jobId": "job_8f2c41",
    "status": "COMPLETE",
    "downloadUrl": "/v1/jobs/job_8f2c41/download"
  }
}
verify.ts, sobre el cuerpo sin procesar
import { createHmac, timingSafeEqual } from 'node:crypto';

// Verifica sobre el cuerpo de solicitud SIN PROCESAR, antes del análisis JSON.
export function verify(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}
en tu flujo de trabajo

Traduce al publicar y abre la solicitud de incorporación de cambios (PR).

Inicia un trabajo desde la integración continua, deja que el webhook firmado te avise cuando termine, descarga el resultado con la estructura del repositorio y abre una solicitud de incorporación de cambios, sin usar el navegador.

.github/workflows/translate.yml
name: Translate on release
on:
  release:
    types: [published]
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Kick off a translation job
        run: |
          curl -sS -X POST https://api.echo-lingua.com/v1/jobs \
            -H "Authorization: Bearer ${{ secrets.ECHO_LINGUA_KEY }}" \
            -H "Content-Type: application/json" \
            -d @job.json
      # Un webhook job.completed firmado abre la PR con los catálogos traducidos.
referencia

Los puntos de conexión que realmente utilizarás.

POST/v1/jobstranslate:writeCrear un trabajo de traducción.
POST/v1/jobs/estimatetranslate:writeSimulación de tamaño y costos, sin crear trabajos.
POST/v1/jobs/plantranslate:writeSimulación de clasificación por entrada.
GET/v1/jobsjobs:readListar tus trabajos.
GET/v1/jobs/{id}jobs:readObtener el estado y los recuentos de un trabajo.
GET/v1/jobs/{id}/downloadjobs:readDescargar el archivo ZIP de salida (con la estructura del repositorio).
GET/v1/jobs/{id}/reviewjobs:readEntradas marcadas para revisión.
POST/v1/jobs/{id}/retrytranslate:writeVolver a ejecutar únicamente las entradas fallidas.
POST/v1/jobs/{id}/canceltranslate:writeCancelar un trabajo en ejecución.
POST/v1/translate/texttranslate:writeTraducir un bloque de texto en línea, sin trabajos.
POST/v1/translate/codetranslate:writeTraducir los literales de cadena en un fragmento de código.
POST/v1/translate/estimatetranslate:writeCalcular el precio de una traducción síncrona, sin costo.
POST/v1/templatestranslate:writeGenerar plantillas PO vacías por idioma.
GET/v1/usagejobs:readUso, costos y límites del periodo actual.

Los puntos de conexión anteriores son los que más usarás. Ver todos los puntos de conexión en la documentación →

Publica todos tus idiomas directamente desde tu canal de desarrollo.

Crea una clave con ámbito, haz un POST con un trabajo y configura el webhook. El cargo fijo de tu primer mes corre por nuestra cuenta.

Obtener una clave de API