{"id":48772531,"url":"https://github.com/technance-foundation/worphling","last_synced_at":"2026-04-13T11:07:03.710Z","repository":{"id":301143495,"uuid":"893155092","full_name":"technance-foundation/worphling","owner":"technance-foundation","description":"🌎 Simplify translation workflow using AI. Synchronize and automate by a single command","archived":false,"fork":false,"pushed_at":"2026-03-26T23:49:55.000Z","size":376,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-27T06:11:32.922Z","etag":null,"topics":["chat-gpt","i18n","multi-language","open-ai","translation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/technance-foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-23T17:18:20.000Z","updated_at":"2026-03-26T23:50:00.000Z","dependencies_parsed_at":"2025-08-13T16:06:28.023Z","dependency_job_id":"5ea11e91-c8a4-400d-8fdb-e8abf35a7a94","html_url":"https://github.com/technance-foundation/worphling","commit_stats":null,"previous_names":["technance-foundation/worphling"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/technance-foundation/worphling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technance-foundation%2Fworphling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technance-foundation%2Fworphling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technance-foundation%2Fworphling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technance-foundation%2Fworphling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technance-foundation","download_url":"https://codeload.github.com/technance-foundation/worphling/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technance-foundation%2Fworphling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31749825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chat-gpt","i18n","multi-language","open-ai","translation"],"created_at":"2026-04-13T11:07:03.626Z","updated_at":"2026-04-13T11:07:03.693Z","avatar_url":"https://github.com/technance-foundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Worphling\n\n**Keep your translations in sync with AI-powered automation.**\n\nWorphling is a CLI for managing localization files end-to-end. It detects missing, outdated, and unused translations, automatically translates new content with AI models such as OpenAI, validates ICU messages and rich-text tags, and produces structured reports suitable for CI and automation.\n\n---\n\n## What Worphling Does\n\nWorphling helps you:\n\n- Automatically translate missing keys using AI\n- Retranslate keys when the source text changes\n- Remove keys that no longer exist in the source locale\n- Validate placeholders, ICU messages, and rich-text tags\n- Generate JSON or Markdown reports\n- Run safely in CI with deterministic behavior and stable exit codes\n\n---\n\n## Install\n\n```bash\npnpm add -D @technance/worphling\n```\n\nOr globally:\n\n```bash\npnpm add -g @technance/worphling\n```\n\n---\n\n## Quick Start\n\n```bash\n# Check the current state of your locale files\nworphling check\n\n# Automatically translate and synchronize everything\nworphling sync --write\n```\n\n---\n\n## The Main Use Case\n\nMost teams use Worphling for this workflow:\n\n1. A source locale such as `en` is the source of truth\n2. Developers add or change source messages\n3. Worphling compares the current source locale against its stored snapshot\n4. Worphling detects missing, outdated, and extra entries\n5. Worphling translates missing or outdated entries with AI\n6. Worphling removes stale keys\n7. CI verifies that everything stays consistent\n\n---\n\n## Commands\n\n### `check`\n\nAnalyze locale files without changing them.\n\n```bash\nworphling check\n```\n\nDetects:\n\n- missing translations\n- extra keys\n- source changes requiring retranslation\n- validation issues\n\nBest for CI and verification.\n\n---\n\n### `translate`\n\n```bash\nworphling translate --write\n```\n\n- translates missing keys\n- retranslates modified source keys\n- does NOT remove extra keys\n\n---\n\n### `fix`\n\n```bash\nworphling fix --write\n```\n\n- removes extra keys\n- no translation\n\n---\n\n### `sync`\n\n```bash\nworphling sync --write\n```\n\nFull lifecycle:\n\n- translate missing\n- retranslate modified\n- remove extra\n\n---\n\n### `report`\n\n```bash\nworphling report --report-file ./.worphling/worphling-report.md\n```\n\nOutputs a standalone report.\n\n---\n\n## Common Flags\n\n\u003e CLI flags override config-level runtime settings.\n\n### `--write`\n\nApply changes to disk.\n\n---\n\n### `--report-file`\n\n```bash\nworphling check --report-file ./.worphling/report.json\n```\n\n---\n\n### `--report-format`\n\n```bash\nworphling report --report-format markdown\n```\n\n---\n\n### `--locales`\n\n```bash\nworphling sync --locales fa,de --write\n```\n\n---\n\n### `--config`\n\n```bash\nworphling check --config ./worphling.config.mjs\n```\n\n---\n\n### `--dry-run`\n\n```bash\nworphling sync --dry-run\n```\n\n---\n\n### `--fail-on-changes`\n\nFail when any diff exists.\n\n```bash\nworphling check --fail-on-changes\n```\n\n---\n\n### `--fail-on-warnings`\n\nFail when warnings exist.\n\n```bash\nworphling check --fail-on-warnings\n```\n\n---\n\n## Configuration\n\n```json\n{\n    \"sourceLocale\": \"en\",\n    \"localesDir\": \"./locales\",\n    \"filePattern\": \"*.json\",\n\n    \"provider\": {\n        \"name\": \"openai\",\n        \"apiKey\": \"YOUR_API_KEY\",\n        \"model\": \"gpt-5.1-2025-11-13\",\n        \"temperature\": 0\n    },\n\n    \"plugin\": {\n        \"name\": \"none\"\n    },\n\n    \"snapshot\": {\n        \"file\": \"./.worphling/.worphling-snapshot.json\"\n    },\n\n    \"output\": {\n        \"sortKeys\": true,\n        \"preserveIndentation\": 2,\n        \"trailingNewline\": true\n    },\n\n    \"validation\": {\n        \"preservePlaceholders\": true,\n        \"preserveIcuSyntax\": true,\n        \"preserveHtmlTags\": true,\n        \"failOnExtraKeys\": false,\n        \"failOnMissingKeys\": true,\n        \"failOnModifiedSource\": false\n    },\n\n    \"translation\": {\n        \"batchSize\": 100,\n        \"maxRetries\": 3,\n        \"concurrency\": 2,\n        \"exactLength\": false,\n        \"contextFile\": \"./translation-context.md\"\n    },\n\n    \"runtime\": {\n        \"reportFile\": \"./.worphling/worphling-report.json\",\n        \"failOnChanges\": false,\n        \"failOnWarnings\": false\n    }\n}\n```\n\n---\n\n## Runtime Behavior (Important)\n\nThe `runtime` section controls failure behavior and reporting defaults.\n\n### Precedence\n\n```\nCLI flags \u003e runtime config \u003e defaults\n```\n\n---\n\n### `failOnChanges`\n\nIf enabled, **any detected diff (missing, extra, modified)** causes failure.\n\n```json\n{\n    \"runtime\": {\n        \"failOnChanges\": true\n    }\n}\n```\n\n---\n\n### `failOnWarnings`\n\nIf enabled, warnings also fail the run.\n\n---\n\n### `reportFile`\n\nDefault output file when `--report-file` is not provided.\n\n---\n\n## Exit Codes\n\n| Code | Meaning               |\n| ---- | --------------------- |\n| `0`  | Success               |\n| `1`  | General runtime error |\n| `2`  | Config error          |\n| `3`  | Validation error      |\n| `4`  | Provider error        |\n\n---\n\n## Typical Workflows\n\n### Local dev\n\n```bash\nworphling sync --write\n```\n\n---\n\n### CI\n\n```bash\nworphling check --fail-on-changes --report-file ./.worphling/worphling-report.json\n```\n\n---\n\n### Generate report\n\n```bash\nworphling report --report-file ./.worphling/worphling-report.md\n```\n\n---\n\n## Recommended Setup\n\n```json\n{\n    \"sourceLocale\": \"en\",\n    \"filePattern\": \"*.json\",\n\n    \"plugin\": {\n        \"name\": \"none\"\n    },\n\n    \"snapshot\": {\n        \"file\": \"./.worphling/.worphling-snapshot.json\"\n    },\n\n    \"validation\": {\n        \"preservePlaceholders\": true,\n        \"preserveIcuSyntax\": true,\n        \"preserveHtmlTags\": true,\n        \"failOnMissingKeys\": true\n    },\n\n    \"runtime\": {\n        \"reportFile\": \"./.worphling/worphling-report.json\",\n        \"failOnChanges\": true\n    }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnance-foundation%2Fworphling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnance-foundation%2Fworphling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnance-foundation%2Fworphling/lists"}