Dolphin is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.
npm install @rootapp/dolphinDolphin is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.
- Installation
- Usage
- Configuration
- Troubleshooting
Dolphin is an automation tool that helps you to localize your app/website strings. It can automatically export, translate and import strings in your projects.
The process is simple to understand:
1. Export the strings from your project based on configuration.
2. Translate and review the strings to the target languages using the specified translator.
3. Import the translated strings back to your project.
Install Dolphin globally with npm/pnpm/yarn:
``shell`
npm install -g @rootapp/dolphin
Check if the installation is successful by running:
`shell`
dolphin --version
Dolphin requires a configuration file to desribe the translation strings and preferred options.
Here's an example of a configuration file:
`yaml`
baseLanguage: en
translator:
agent: openai
mode: interactive
model: gpt-4o
localizations:
- id: hostapp
path: TranditionalXcodeDemo/${LANGUAGE}.lproj/Localizable.strings
format: strings
languages:
- fr
- ja
- zh-Hans
It 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.
For more details on how to write a configuration file, please check the Configuration section.
Dolphin defines an interface for translators to implement, which is responsible for translating source strings into target languages.
> I'm still working on adding more translators. PRs are welcome!
#### openai
This 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.
The 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. To use a custom OpenAI-compatible endpoint, you can provide the baseUrl option to the translator.
#### api
The 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.
> Related spec and code of the API service (using Next.js as an example) can be found in the api folder.
>
> You can deploy the API service to your own server or managed platforms (like Vercel) and change the baseUrl to your server address.
>
> Note: the provided code is just for demo purpose, it's not production ready. You should use at your own risk.
We 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.)
By default, Dolphin looks for a file named dolphin.yml in the current working directory.
`shell`
dolphin localize
You can specify a different file with the --config option.
`shell`
dolphin localize --config path/to/dolphin.yml
An interactive shell like below will guide you through the translation process.
Configration file is a YAML file with the following structure:
`yaml
baseLanguage: [required, language code]
translator:
agent: [required, translator name]
mode: [required, translator mode]
.... [extra config for the translator]
globalContext: [optional, custom translation context]
localizations:
- id: [required, string, to identify the localization]
path: [required, path to strings]
format: [required, string format]
languages:
- [required, language code]
- [required, language code]
...
- id: [required, string, to identify the localization]
path: [required, path to strings]
format: [required, string format]
languages:
- [required, language code]
- [required, language code]
...
...
`
Language codes can be any commonly used ones, such as en-US, ja, es, etc. As long as it is supported by the translator.
#### baseLanguage
The source language of the strings, which is used to translate from.
#### translator
Supported translators:
- 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.baseUrl
- api: Dolphin API. You need to provide the to the API endpoint.
Supported modes:
- 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.
#### globalContext
The context of the translation. It will be used to provide more information to the translator.
> For example, if you don't want specific words to skipped, you can say "xxx is a specific term which should be translated."
#### id
Arbitary unique id across localizations, used to identify the specific localization in the project.
#### format
- text: Plain text
- json: JSON file, usually used in frontend apps
- xliff: Xliff file
- strings: Apple Localized Strings (with "key" = "value" format)
- xloc: Xcode Localization Catalog
- xcode: Xcode project (Using Xcode built-in localization tool to import/export strings)
> 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.
#### path
The path to the localization file. You can use ${LANGUAGE} as the language placeholder.
> For xcode format, the path should be .xcodeproj folder.
#### languages
The target languages to translate to.
> For xcode format, there's no need to provide languages as they can be inferred from the project itself.
For more examples, please check the Examples repo.
By 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.
Dolphin 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.
Run the following command and answer the questions to release a new version:
`
pnpm release
Commit 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.