Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rootstudiohq/dolphin

Dolphin is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.
https://github.com/rootstudiohq/dolphin

i18n internalization l10n localization translation

Last synced: 10 days ago
JSON representation

Dolphin is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.

Awesome Lists containing this project

README 

          
**Dolphin** is an innovative, automated internationalization (i18n) service designed to integrate seamlessly into your development pipeline.



- [Installation](#Installation)

- [Usage](#Usage)

- [Configuration](#Configuration)

- [Troubleshooting](#Troubleshooting)



## How it works?



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.



## Installation



Install Dolphin globally with npm/pnpm/yarn:



```shell

npm install -g @rootapp/dolphin

```



Check if the installation is successful by running:



```shell

dolphin --version

```



## Usage



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](#Configuration) section.



### Translator



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](https://openrouter.ai/models?fmt=cards&supported_parameters=response_format&order=top-weekly). 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](https://github.com/icodesign/dolphin/tree/main/apps/api/).

>

> 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.)



### Running Dolphin



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.



![Output Screenshot](assets/output-screenshot.jpg)



## Configuration



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.

- **api**: Dolphin API. You need to provide the `baseUrl` 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.



## Examples



For more examples, please check the [Examples](https://github.com/icodesign/dolphin/tree/main/examples/) repo.



## Troubleshooting



### Logs



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.



### Exported Strings



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.



## Development



### Release a new version



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.