YAMLFish Documentation

Core Concepts

YAMLFish is a tool designed to help you manage your YAML translations.
It comes with a web interface and a CLI to make it easy for you to manage your translations.

Push your translations with the CLI, straight from your terminal or from a CI/CD pipeline.
Have anyone in your team view and update translations on the web interface, without having to deal with the YAML files directly.
Pull translations with the CLI, without loosing your translation files structure.

Locales

Locales are the languages you want to support in your application.
YAMLFish supports an unlimited number of locales.

Branches

Branches are a way to manage different versions of your translations.
You can create a new branch, push translations to it, and pull translations from it.
This is useful when you want to work on a new feature or fix a bug without affecting the main branch.
This is also the preferred way for non-tech people to propose changes to translations without disrupting the development process.
Once your changes are ready, the branch can be merged into the main branch, effectively updating all translations.

Web Interface

The web interface allows you to manage your translations easily.
You can create, update, and delete translations, as well as manage branches and locales.

CLI

The CLI allows you to manage your translations from your terminal.
You only need to learn our 2 commands to start using YAMLFish from your terminal.

Installation & configuration

YAMLFish is available as a Ruby gem so you can install it with gem install yamlfish --pre.
You can then configure it by creating a .yamlfish.yml file at the root of your app, with the following content:


  api_key: YOUR_API_KEY

  project_token: YOUR_PROJECT_TOKEN

  locales_path: where/your/locales/are # Default is config/locales

Those secrets can be found in the footer of your project's page on YAMLFish.

Push

> yamlfish push LOCALE_IDENTIFIER [--branch BRANCH_NAME] [-k, --keep-unmentioned-keys] The push command will look for your translations files in the config/locales directory by default and push them to the YAMLFish server.
You can specify a branch with the --branch option.

Warning: Note that this will overwrite all translations on the server with the translations in your files.
By default, the keys that are not mentioned in your files will be archived on YAMLFish.
Use the -k (--keep-unmentioned-keys) option to keep them.

Pull

> yamlfish pull LOCALE_IDENTIFIER [--branch BRANCH_NAME] [--inplace] [--force-update] The pull command will fetch translations for the given locale from the YAMLFish server and save them in your config/locales directory by default.
By default, it will create or overwrite a file for each locale, such as config/locales/en.yml
You can specify a branch with the --branch option.
The --inplace option will update the translations in place, without creating new files, it will only update existing translations as it could not know where new translations would go.

When using --inplace, only the files that have updates are modified. For now, YAMLFish proceeds by rewriting the whole file, this means that comments are not saved and especially that the style of the file may change. To keep files consistent, you can use the --force-update option, which will update all files, even if they do not contain any changes.

Workflow

YAMLFish is not aware of your application, your version control system, or your deployment process, It is only aware of the translations that are pushed to it. Depending on your structure and needs, you can integrate YAMLFish in your workflow in different ways.
One important thing to note, is that each push will completely overwrite the translations stored on YAMLFish. This is fine if you're alone but obviously not if you're working in a distributed team.

Suggested framework

You most likely have a main locale, the one you use in your development process, and secondary locales, the ones that need to go through a translation process.

A good way to integrate YAMLFish is to think about "source of truth" for your translations:

For your main locale, the source of truth is your codebase, you want to push translations from your codebase to YAMLFish.
A good practice for this is to only push translations from a CI/CD pipeline, where you can ensure that the translations are up to date and that you're not overwriting someone else's work.

For your secondary locales, the source of truth is YAMLFish, you want to pull translations from YAMLFish into your codebase.

Example workflows

Developer is working on a new feature that affects translations

Developer works on their feature
Once the changes on the translations are final, Developer pushes translations to yamlfish on a newly created branch: yamlfish push en --branch some-feature
On YAMLFish, Translator updates translations on secondary locales for this new branch
Developer merges their code
CI/CD pipeline pushes translations to YAMLFish on the main branch: yamlfish push en
Developer merges the branch on YAMLFish
Developer pulls translations for secondary locales to their codebase: yamlfish pull fr

Translator wants to change a main locale translation key

Translator creates a branch on YAMLFish
Translator updates the translation key
Developer pulls translations for the branch to their codebase: yamlfish pull en
Developer closes the branch on YAMLFish

Translator wants to change a secondary locale translation key

Translator updates the translation key on the main branch
Developer pulls translations for the branch to their codebase: yamlfish pull fr