{"id":20760527,"url":"https://github.com/modernice/dragoman","last_synced_at":"2025-07-21T08:34:20.013Z","repository":{"id":115064611,"uuid":"314334586","full_name":"modernice/dragoman","owner":"modernice","description":"Translator for structured documents.","archived":false,"fork":false,"pushed_at":"2024-04-27T14:27:29.000Z","size":241,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-04T21:56:08.830Z","etag":null,"topics":["deepl","document","dragoman","go","golang","i18n","json","placeholders","structured","translate"],"latest_commit_sha":null,"homepage":"","language":"Go","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/modernice.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-19T18:22:18.000Z","updated_at":"2024-06-06T16:58:22.000Z","dependencies_parsed_at":"2023-12-22T18:27:28.816Z","dependency_job_id":"62611a1a-5e3c-4c4b-9d68-7c69685e3f65","html_url":"https://github.com/modernice/dragoman","commit_stats":null,"previous_names":["bounoable/dragoman"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/modernice/dragoman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modernice%2Fdragoman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modernice%2Fdragoman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modernice%2Fdragoman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modernice%2Fdragoman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modernice","download_url":"https://codeload.github.com/modernice/dragoman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modernice%2Fdragoman/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266267369,"owners_count":23902354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["deepl","document","dragoman","go","golang","i18n","json","placeholders","structured","translate"],"created_at":"2024-11-17T10:14:08.739Z","updated_at":"2025-07-21T08:34:19.990Z","avatar_url":"https://github.com/modernice.png","language":"Go","readme":"# Dragoman - Translator for Structured Documents\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/modernice/dragoman)](https://pkg.go.dev/github.com/modernice/dragoman) ![Test](https://github.com/modernice/dragoman/workflows/Test/badge.svg)\n\nDragoman is an AI-powered tool for translating structured documents like JSON,\nXML, YAML. The tool's key feature is its ability to maintain the document's \nstructure during translation - keeping elements such as JSON keys and placeholders intact.\n\nDragoman is available as both a CLI tool and a Go library. This means you can\nuse it directly from your terminal for one-off tasks, or integrate it into your\nGo applications for more complex use cases.\n\n\u003csub\u003e\nIf you're looking for a version of Dragoman that leverages conventional\ntranslation services like Google Translate or DeepL, check out the\n\u003ca href=\"https://github.com/modernice/dragoman/tree/freeze\"\u003efreeze\u003c/a\u003e branch\nof this repository. The previous implementation manually extracted texts from\nthe input files, translated them using DeepL or Google Translate, and reinserted\nthe translated pieces back into the original documents.\n\u003c/sub\u003e\n\n## Installation\n\nDragoman can be installed directly using Go's built-in package manager:\n\n```bash\ngo install github.com/modernice/dragoman/cmd/dragoman@latest\n```\n\nTo add Dragoman to your Go project, install using `go get`:\n\n```bash\ngo get github.com/modernice/dragoman\n```\n\n## Usage\n\nThe basic usage of Dragoman is as follows:\n\n```bash\ndragoman source.json\n```\n\nThis command will translate the content of `source.json` to English and print\nthe translated document to stdout. The source language is automatically detected\nby default, but if you want to specify the source or target languages, you need\nto use the `--from` or `--to` option.\n\n### Full list of available options\n\n**`-f` or `--from`**\n\nThe source language of the document. It can be specified in any format that a\nhuman would understand (like 'English', 'German', 'French', etc.). If not\nprovided, it defaults to 'auto', meaning the language is automatically detected.\n\n```bash\ndragoman translate source.json --from English\n```\n\n**`-t` or `--to`**\n\nThe target language to which the document will be translated. It can be\nspecified in any format that a human would understand (like 'English', 'German',\n'French', etc.). If not provided, it defaults to 'English'.\n\n```bash\ndragoman translate source.json --to French\n```\n\n**`-o` or `--out`**\n\nThe path to the output file where the translated content will be saved. If this\noption is not provided, the translated content will be printed to stdout.\n\n```bash\ndragoman translate source.json --out target.json\n```\n\n**`--split-chunks`**\n\nSplit the source document into chunks before translating. This can help to fit\nthe documents into the context size of OpenAI's models. Each line that starts\nwith one of the provided prefixes will create a new chunk.\n\n**Example: Split a Markdown file into chunks when encountering H2 and H3 headings:**\n```bash\ndragoman translate source.json --split-chunks \"## \" --split-chunks \"### \"\n```\n\n**`-u` or `--update`**\n\nEnable this option to only translate missing fields from the source file that\nare missing in the output file. This option requires the source and output files\nto be JSON!\n\n```bash\ndragoman translate source.json --out target.json --update\n```\n\n#### Example\n\nWhen you add new translations to your JSON source file, you can use the `--update`\noption to only translate the newly added fields and merge them into the output file.\n\n```json\n// en.json\n{\n\t\"hello\": \"Hello, world!\",\n\t\"contact\": {\n\t\t\"email\": \"hello@example.com\",\n\t\t\"response\": \"Thank you for your message.\"\n\t}\n}\n```\n\n```json\n// de.json\n{\n\t\"hello\": \"Hallo, Welt!\",\n\t\"contact\": {\n\t\t\"email\": \"hallo@example.com\"\n\t}\n}\n```\n\n```bash\ndragoman translate en.json --out de.json --update\n```\n\nResult:\n\n```json\n// de.json\n{\n\t\"hello\": \"Hallo, Welt!\",\n\t\"contact\": {\n\t\t\"email\": \"hallo@example.com\",\n\t\t\"response\": \"Vielen Dank für deine Nachricht.\"\n\t}\n}\n```\n\n**`-p` or `--preserve`**\n\nThis option allows you to specify a list of specific words or phrases, separated by commas, that you want to remain unchanged during the translation process. It's particularly useful for ensuring that certain terms, which may have significance in their original form or are used in specific contexts (like code, trademarks, or names), are not altered. These specified terms will be recognized and preserved whether they appear in isolation or as part of larger strings. This feature is especially handy for content that includes embedded terms within other elements, such as HTML tags. For instance, using --preserve ensures that a term like \u003cspan class=\"font-bold\"\u003eDrago\u003c/span\u003eman retains its original form post-translation. Note that the effectiveness of this feature may vary depending on the language model used, and it is optimized for use with OpenAI's GPT models.\n\n```bash\ndragoman translate source.json --preserve Dragoman\n```\n\n**`-v` or `--verbose`**\n\nA flag that, if provided, makes the CLI provide more detailed output about the\nprocess and result of the translation.\n\n```bash\ndragoman translate source.json --verbose\n```\n\n**`-h` or `--help`**\n\nA flag that displays a help message detailing how to use the command and its options.\n\n```bash\ndragoman --help\n```\n\n## Use as Library\n\nBesides the CLI tool, Dragoman can also be used as a Go library in your own\napplications. This allows you to build the Dragoman translation capabilities\ndirectly into your own Go programs.\n\n### Example: Basic Translation\n\nIn this example, we load a JSON file and translate its content using the default\nsource and target languages (automatic detection and English, respectively).\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\n\t\"github.com/modernice/dragoman\"\n\t\"github.com/modernice/dragoman/openai\"\n)\n\nfunc main() {\n\tcontent, _ := io.ReadFile(\"source.json\")\n\t\n\tservice := openai.New()\n\ttranslator := dragoman.New(service)\n\t\n\ttranslated, _ := translator.Translate(context.TODO(), string(content))\n\n\tfmt.Println(translated)\n}\n```\n\n### Example: Translation with Preserved Words\n\nIn this example, we translate a JSON file, specifying some preserved words that\nshould not be translated.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\n\t\"github.com/modernice/dragoman\"\n\t\"github.com/modernice/dragoman/openai\"\n)\n\nfunc main() {\n\tcontent, _ := io.ReadFile(\"source.json\")\n\t\n\tservice := openai.New()\n\ttranslator := dragoman.New(service)\n\t\n\ttranslated, _ := translator.Translate(\n\t\tcontext.TODO(),\n\t\tstring(content),\n\t\tdragoman.Preserve([]string{\"Dragoman\", \"OpenAI\"}),\n\t)\n\n\tfmt.Println(translated)\n}\n```\n\n### Example: Translation with Specific Source and Target Languages\n\nIn this example, we translate a JSON file from English to French, specifying the\nsource and target languages.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\n\t\"github.com/modernice/dragoman\"\n\t\"github.com/modernice/dragoman/openai\"\n)\n\nfunc main() {\n\tcontent, _ := io.ReadFile(\"source.json\")\n\t\n\tservice := openai.New()\n\ttranslator := dragoman.New(service)\n\t\n\ttranslated, _ := translator.Translate(\n\t\tcontext.TODO(),\n\t\tstring(content),\n\t\tdragoman.Source(\"English\"),\n\t\tdragoman.Target(\"French\"),\n\t)\n\n\tfmt.Println(translated)\n}\n```\n\n## License\n\n[MIT](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodernice%2Fdragoman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodernice%2Fdragoman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodernice%2Fdragoman/lists"}