{"id":36543594,"url":"https://github.com/rootstudiohq/dolphin","last_synced_at":"2026-01-12T05:52:33.906Z","repository":{"id":249384211,"uuid":"831349753","full_name":"rootstudiohq/dolphin","owner":"rootstudiohq","description":"Dolphin is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.","archived":false,"fork":false,"pushed_at":"2025-11-07T10:58:55.000Z","size":461,"stargazers_count":25,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-26T21:56:50.853Z","etag":null,"topics":["i18n","internalization","l10n","localization","translation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rootstudiohq.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-20T09:46:46.000Z","updated_at":"2025-11-07T10:57:56.000Z","dependencies_parsed_at":"2024-07-20T12:23:55.076Z","dependency_job_id":"d3d7ab63-505c-4a50-83e8-adb603913ece","html_url":"https://github.com/rootstudiohq/dolphin","commit_stats":null,"previous_names":["icodesign/dolphin","rootstudiohq/dolphin"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/rootstudiohq/dolphin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootstudiohq%2Fdolphin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootstudiohq%2Fdolphin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootstudiohq%2Fdolphin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootstudiohq%2Fdolphin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootstudiohq","download_url":"https://codeload.github.com/rootstudiohq/dolphin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootstudiohq%2Fdolphin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["i18n","internalization","l10n","localization","translation"],"created_at":"2026-01-12T05:52:33.206Z","updated_at":"2026-01-12T05:52:33.901Z","avatar_url":"https://github.com/rootstudiohq.png","language":"TypeScript","readme":"**Dolphin** is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.\n\n\u003c!--ts--\u003e\n\n- [Installation](#Installation)\n- [Usage](#Usage)\n- [Configuration](#Configuration)\n- [Troubleshooting](#Troubleshooting)\n\n\u003c!--te--\u003e\n\n## How it works?\n\nDolphin is an automation tool that helps you to localize your app/website strings. It can automatically export, translate and import strings in your projects.\n\nThe process is simple to understand:\n\n1. **Export** the strings from your project based on configuration.\n\n2. **Translate** and review the strings to the target languages using the specified translator.\n\n3. **Import** the translated strings back to your project.\n\n## Installation\n\nInstall Dolphin globally with npm/pnpm/yarn:\n\n```shell\nnpm install -g @rootapp/dolphin\n```\n\nCheck if the installation is successful by running:\n\n```shell\ndolphin --version\n```\n\n## Usage\n\nDolphin requires a configuration file to desribe the translation strings and preferred options.\n\nHere's an example of a configuration file:\n\n```yaml\nbaseLanguage: en\ntranslator:\n  agent: openai\n  mode: interactive\n  model: gpt-4o\nlocalizations:\n  - id: hostapp\n    path: TranditionalXcodeDemo/${LANGUAGE}.lproj/Localizable.strings\n    format: strings\n    languages:\n      - fr\n      - ja\n      - zh-Hans\n```\n\nIt means that Dolphin will look for a file named `Localizable.strings` in the `TranditionalXcodeDemo/en.lproj` directory whose format is `Apple Localized Strings`. And then translate it to French, Japanese, and Simplified Chinese with the `api` translator.\n\nFor more details on how to write a configuration file, please check the [Configuration](#Configuration) section.\n\n### Translator\n\nDolphin defines an interface for translators to implement, which is responsible for translating source strings into target languages.\n\n\u003e I'm still working on adding more translators. PRs are welcome!\n\n#### openai\n\nThis is a local translator which uses OpenAI API to translate strings. To use this translator, you need to provide the OpenAI API key as an environment variable (`OPENAI_API_KEY`) or pass it to the translator with the `apiKey` option. Optionally, you can specify the model to use with the `model` option. By default, it uses `gpt-4o` model.\n\nThe translator also supports any openai-comptable models, such as gemini and deepseek. However, the model needs support json response format, for major supported models, please refer to [OpenRouter website](https://openrouter.ai/models?fmt=cards\u0026supported_parameters=response_format\u0026order=top-weekly). To use a custom OpenAI-compatible endpoint, you can provide the `baseUrl` option to the translator.\n\n#### api\n\nThe `api` translator is a built-in translator that uses the Dolphin API (or compatible) service to translate strings. You need to provide the `baseUrl` to the API endpoint.\n\n\u003e Related spec and code of the API service (using Next.js as an example) can be found in the [api folder](https://github.com/icodesign/dolphin/tree/main/apps/api/).\n\u003e\n\u003e You can deploy the API service to your own server or managed platforms (like Vercel) and change the `baseUrl` to your server address.\n\u003e\n\u003e Note: the provided code is just for demo purpose, it's not production ready. You should use at your own risk.\n\nWe also provide a hosted API service for you to use. Currently it's still in closed testing phase. If you're interested, please contact me. (You should be smart enough to find my email address.)\n\n### Running Dolphin\n\nBy default, Dolphin looks for a file named `dolphin.yml` in the current working directory.\n\n```shell\ndolphin localize\n```\n\nYou can specify a different file with the `--config` option.\n\n```shell\ndolphin localize --config path/to/dolphin.yml\n```\n\nAn interactive shell like below will guide you through the translation process.\n\n![Output Screenshot](assets/output-screenshot.jpg)\n\n## Configuration\n\nConfigration file is a YAML file with the following structure:\n\n```yaml\nbaseLanguage: [required, language code]\n\ntranslator:\n  agent: [required, translator name]\n  mode: [required, translator mode]\n  .... [extra config for the translator]\n\nglobalContext: [optional, custom translation context]\n\nlocalizations:\n  - id: [required, string, to identify the localization]\n    path: [required, path to strings]\n    format: [required, string format]\n    languages:\n      - [required, language code]\n      - [required, language code]\n      ...\n\n  - id: [required, string, to identify the localization]\n    path: [required, path to strings]\n    format: [required, string format]\n    languages:\n      - [required, language code]\n      - [required, language code]\n      ...\n\n  ...\n```\n\nLanguage codes can be any commonly used ones, such as `en-US`, `ja`, `es`, etc. As long as it is supported by the translator.\n\n#### baseLanguage\n\nThe source language of the strings, which is used to translate from.\n\n#### translator\n\nSupported translators:\n\n- **openai**: OpenAI API. You need to provide the OpenAI API key as an environment variable (`OPENAI_API_KEY`) or pass it to the translator with the `apiKey` option. By default, it uses `gpt-4o` model, which can be customized with the `model` option. Optionally, you can provide the `baseUrl` to use a custom OpenAI-compatible endpoint.\n- **api**: Dolphin API. You need to provide the `baseUrl` to the API endpoint.\n\nSupported modes:\n\n- **interactive**: In interactive mode, after strings are translated, Dolphin will ask you to review the result to approve or ask the agent to refine. By default, this mode is not enabled.\n\n#### globalContext\n\nThe context of the translation. It will be used to provide more information to the translator.\n\n\u003e For example, if you don't want specific words to skipped, you can say \"xxx is a specific term which should be translated.\"\n\n#### id\n\nArbitary unique id across localizations, used to identify the specific localization in the project.\n\n#### format\n\n- **text**: Plain text\n- **json**: JSON file, usually used in frontend apps\n- **xliff**: Xliff file\n- **strings**: Apple Localized Strings (with `\"key\" = \"value\"` format)\n- **xloc**: Xcode Localization Catalog\n- **xcode**: Xcode project (Using Xcode built-in localization tool to import/export strings)\n\n\u003e It's generally recommended to avoid using `xcode` format if possible as it needs to build the whole Xcode project which can be time-consuming.\n\n#### path\n\nThe path to the localization file. You can use `${LANGUAGE}` as the language placeholder.\n\n\u003e For `xcode` format, the path should be `.xcodeproj` folder.\n\n#### languages\n\nThe target languages to translate to.\n\n\u003e For `xcode` format, there's no need to provide languages as they can be inferred from the project itself.\n\n## Examples\n\nFor more examples, please check the [Examples](https://github.com/icodesign/dolphin/tree/main/examples/) repo.\n\n## Troubleshooting\n\n### Logs\n\nBy default, shell wil only show the major output. To see more details, you can check the log file at `~/Library/Logs/Dolphin/dolphin-[date].log` (on macOS). The log directory will also be printed at the top of the shell output.\n\n### Exported Strings\n\nDolphin will export the translated strings to the `.dolphin` folder in the same directory of the configuration file. You can check if the exported strings are correct there.\n\n## Development\n\n### Release a new version\n\nRun the following command and answer the questions to release a new version:\n\n```\npnpm release\n```\n\nCommit the changes and push to the remote repository. `changeset` will automatically create a PR to create a new release and publish it to the npm registry.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootstudiohq%2Fdolphin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootstudiohq%2Fdolphin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootstudiohq%2Fdolphin/lists"}