fkirc · fkirc · Feb 12, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,22 @@
+# AGENTS.md
+
+Always do a build before executing tests:
+
+- npm run build
+- npm run test
+
+Do NOT work on files in the dist-folder, because the dist-folder is auto-generated by the npm run build command.
+
+When working on unit-tests, see docs/DEV_MANIFESTO.md for details regarding our test philosophy.
+
+When asked for new features, only implement the logic that is requested. Do not implement new logic just because you assume that a user-base exists for it.
+
+## Code Reviews
+
+Do code reviews from the eyes of a critical senior dev, and consider the following things:
+
+- Only review differences between the current branch and the master-branch.
+- Check if the current branch is up-to-date with the master-branch. If not, then suggest to pull from master.
+- Check critically if logic works as intended.
+- Check critical if changes introduce regression.
+- Check for obvious code smells or spelling mistakes.
diff --git a/CNAME b/CNAME
diff --git a/README-es.md b/README-es.md
@@ -6,14 +6,8 @@
 
 macOS/Ubuntu/Windows: [![Actions Status](https://github.com/fkirc/attranslate/workflows/Tests/badge.svg/?branch=master)](https://github.com/fkirc/attranslate/actions?query=branch%3Amaster)
 
-`attranslate` es una herramienta para sincronizar archivos de traducción, incluyendo JSON/YAML/XML y otros formatos.
-A diferencia de los servicios de pago, cualquier desarrollador puede integrar `attranslate` en cuestión de minutos.
-`attranslate` dejará las traducciones existentes sin cambios y solo sincronizará las nuevas traducciones.
-
-Opcionalmente `attranslate` trabaja con servicios de traducción automática.
-Por ejemplo, supongamos que un servicio de traducción logra un 80% de traducciones correctas.
-Con `attranslate`, una solución rápida del 20% restante puede ser más rápida que hacer todo a mano.
-Aparte de eso, `attranslate` admite traducciones puramente manuales o incluso conversiones de formato de archivo sin cambiar el idioma.
+`attranslate` es una herramienta CLI para sincronizar archivos de traducción (JSON/YAML/XML) diseñada para asistir a Agentes de Código en traducir eficientemente con uso mínimo de tokens.
+Las traducciones existentes permanecen sin cambios; solo se sincronizan las nuevas cadenas de texto.
 
 # Funciones
 
@@ -25,103 +19,85 @@ Por lo tanto, siempre que no esté satisfecho con los resultados producidos, `at
 
 ## Servicios disponibles
 
-`attranslate` admite los siguientes servicios de traducción; Muchos de ellos son gratis:
+- `agent`: Para usar con Agentes de Código. Solicita al agente traducir nuevas cadenas vía stdin cuando se detectan.
 
-- `openai`: Utiliza un modelo como ChatGPT; gratis hasta un límite
-- [google-translate](https://cloud.google.com/translate): Necesita una cuenta de GCloud; gratis hasta un límite
-- [azure](https://azure.microsoft.com/en-us/services/cognitive-services/translator-text-api/): Necesita una cuenta de Microsoft; cuesta dinero
-- `sync-without-translate`: No cambia el idioma. Esto puede ser útil para convertir entre formatos de archivo o para mantener diferencias específicas de la región.
-- `manual`: Traducir textos manualmente
+Otros servicios (openai, google-translate, azure, manual, typechat, sync-without-translate) están deprecados pero se retienen para compatibilidad hacia atrás.
 
 # Ejemplos de uso
 
-Traducir un solo archivo es tan simple como la siguiente línea:
+Traducir un archivo único es tan simple como la siguiente línea:
 
-    attranslate --srcFile=json-simple/en.json --srcLng=English --srcFormat=nested-json --targetFile=json-simple/de.json --targetLng=German --targetFormat=nested-json --service=openai
+```
+attranslate --srcFile=en.json --srcLng=English --format=json --targetFile=es.json --targetLng=Spanish --service=agent
+```
 
-Si tiene varios idiomas de destino, necesitará varias llamadas a `attranslate`.
-Puede escribir algo como el siguiente script:
+Para varios idiomas de destino, invoca `attranslate` para cada uno:
 
 ```bash
-# Este ejemplo traduce un archivo JSON en inglés a español y alemán.
-BASE_DIR="json-advanced"
-SERVICE_ACCOUNT_KEY="gcloud/gcloud_service_account.json"
-COMMON_ARGS=( "--srcLng=en" "--srcFormat=nested-json" "--targetFormat=nested-json" "--service=google-translate" "--serviceConfig=$SERVICE_ACCOUNT_KEY" )
+attranslate --srcFile=en/fruits.json --targetFile=es/fruits.json --targetLng=Spanish --srcLng=English --format=json --service=agent
+attranslate --srcFile=en/fruits.json --targetFile=de/fruits.json --targetLng=German --srcLng=English --format=json --service=agent
+```
 
-# instalar attranslate si aún no está instalado
-attranslate --version || npm install --global attranslate
+# Instalación
 
-attranslate --srcFile=$BASE_DIR/en/fruits.json --targetFile=$BASE_DIR/es/fruits.json --targetLng=es "${COMMON_ARGS[@]}"
-attranslate --srcFile=$BASE_DIR/en/fruits.json --targetFile=$BASE_DIR/de/fruits.json --targetLng=de "${COMMON_ARGS[@]}"
+Instalar globalmente:
+```bash
+npm install --global attranslate
 ```
 
-Del mismo modo, puede utilizar `attranslate` para convertir entre formatos de archivo.
-Ver [scripts de ejemplo](https://github.com/fkirc/attranslate/tree/master/sample-scripts) para más ejemplos.
-
-# Guía de integración
+O en un proyecto Node.js:
+```bash
+npm install --save-dev attranslate
+```
 
-En primer lugar, asegúrese de que [nodejs](https://nodejs.org/) está instalado en el equipo.
-Una vez que tengas `nodejs`, puede instalar `attranslate` Vía:
+# Opciones de uso
 
-`npm install --global attranslate`
+Ejecuta `attranslate --help` para ver una lista de opciones disponibles:
 
-Alternativamente, si usted es un desarrollador de JavaScript, entonces debe instalar `attranslate` Vía:
+```
+Usage: attranslate [options]
+
+Options:
+  --srcFile <sourceFile>             The source file to be translated
+  --srcLng <sourceLanguage>          The source language
+  --targetFile <targetFile>          The target file for the translations
+  --targetLng <targetLanguage>       The target language
+  --format <format>                  Uno de "flat-json", "nested-json", "json", "yaml", "po", "xml", "ios-strings", "arb", "csv"
+  --service <translationService>     "agent"
+  -v, --version                      output the version number
+  -h, --help                         display help for command
+```
 
-`npm install --save-dev attranslate`
+## Ejemplos de Prompt
 
-A continuación, debe escribir un script específico del proyecto que invoque `attranslate` para sus archivos específicos.
-Ver [scripts de ejemplo](https://github.com/fkirc/attranslate/tree/master/sample-scripts) para obtener orientación sobre cómo traducir los archivos específicos del proyecto.
+Se recomienda expandir tu AGENTS.md/CLAUDE.md o similar para instruir a tus Agentes de Código sobre cómo deben hacer traducciones.
+Por ejemplo, agrega algo como esto a tu prompt del sistema:
 
-# Opciones de uso
+```
+Al realizar traducciones, recuerda que estás desarrollando una aplicación de salud para profesionales médicos. Términos técnicos como 'EKG', 'MRI', 'CT scan', 'blood pressure', 'pulse oximeter' y 'vital signs' deben permanecer en inglés. Por favor, mantén la terminología médica apropiada y un tono formal en las traducciones.
+Invoca `attranslate` después de agregar una nueva traducción al archivo en.json en inglés.
+Por ejemplo:
+attranslate --service=agent --srcFile=translations/en.json --targetFile=translations/es.json --targetLng=Spanish --srcLng=English --format=json
+```
 
-Correr `attranslate --help` para ver una lista de opciones disponibles:
+Para reducir el uso de contexto, esto puede envolverse en una declaración condicional:
 
 ```
-    Usage: attranslate [options]
-
-    Options:
-      --srcFile <sourceFile>              The source file to be translated
-      --srcLng <sourceLanguage>           A language code for the source language
-      --srcFormat <sourceFileFormat>      One of "flat-json", "nested-json",
-                                          "yaml", "po", "xml", "ios-strings",
-                                          "arb", "csv"
-      --targetFile <targetFile>           The target file for the translations
-      --targetLng <targetLanguage>        A language code for the target language
-      --targetFormat <targetFileFormat>   One of "flat-json", "nested-json",
-                                          "yaml", "po", "xml", "ios-strings",
-                                          "arb", "csv"
-      --service <translationService>      One of "openai", "manual",
-                                          "sync-without-translate",
-                                          "google-translate", "azure"
-      --serviceConfig <serviceKey>        supply configuration for a translation
-                                          service (either a path to a key-file or
-                                          an API-key)
-      --matcher <matcher>                 An optional feature for string replacements. One of "none", "icu", "i18next",
-                                          "sprintf" (default: "none")
-      --prompt <customPrompt>             Prompt opcional para guiar al servicio de traducción. Útil para especificar
-                                          términos técnicos que no deben traducirse u otras preferencias de traducción.
-      -v, --version                       output the version number
+Al agregar nuevas claves de traducción, consulta <some-explanation.md> para ver cómo deben hacerse las nuevas traducciones.
 ```
 
-## Ejemplos de Prompt
+# Flujo de trabajo del agente (basado en stdin)
 
-Puedes usar el parámetro `--prompt` para proporcionar instrucciones específicas al servicio de traducción. Aquí tienes un ejemplo:
+Cuando uses `--service=agent`, attranslate imprimirá una lista de fuentes faltantes e instrucciones para el agente. El agente debe proporcionar una traducción por línea, en el mismo orden, y canalizarlas a attranslate vía stdin. Ejemplo:
 
-```bash
-attranslate --srcFile=json-simple/en.json --srcLng=English --srcFormat=nested-json \
-           --targetFile=json-simple/es.json --targetLng=Spanish --targetFormat=nested-json \
-           --service=openai \
-           --prompt="Estoy desarrollando una aplicación de salud para profesionales médicos. Términos técnicos como 'EKG', 'MRI', 'CT scan', 'blood pressure', 'pulse oximeter' y 'vital signs' deben permanecer en inglés. Por favor, mantenga la terminología médica adecuada y un tono formal en las traducciones."
+```
+attranslate --srcFile=en.json --srcLng=English --format=json --targetFile=es.json --targetLng=Spanish --service=agent
 ```
 
-Este prompt asegurará que los términos técnicos permanezcan en inglés mientras se traduce el resto del contenido. Puedes personalizar el prompt según tus necesidades específicas, como:
-- Especificar qué términos no deben traducirse
-- Solicitar reglas específicas de capitalización
-- Proporcionar contexto sobre el dominio de tu aplicación
-- Establecer preferencias de tono o estilo para las traducciones
-
-# Contribuidores
+Luego el agente canaliza las traducciones:
 
-Nos gustaría agradecer a todos los contribuidores que han ayudado a mejorar attranslate:
+```
+echo -e "<traducción1>\n<traducción2>\n..." | attranslate --srcFile=en.json --srcLng=English --format=json --targetFile=es.json --targetLng=Spanish --service=agent
+```
 
-- [@esuljic](https://github.com/esuljic): Agregó la característica de parámetro de prompt para servicios de IA (OpenAI y TypeChat).
+Nota: la primera ejecución (sin canalizar stdin) sale con un código distinto de cero por diseño; esto se puede usar en CI/CD para detectar traducciones faltantes.