Our Rust projects are using Fluent for translations. Each of our translatable repositories will have a leading i18n directory in the project root, which has files organized in this format: i18n/{language-code}/{cargo-crate}.ftl.

Fluent translations do not have to be exactly 1:1 translations of the English text. If you have a better expression in your language for the text that is being translated, use the language that is most natural in your language instead. Your translations will remain valid regardless of what changes we make to the English text. But over time we may add or remove keys that will require future translations. You may look for i18n(en): commits since these may signal additions or removals that have been performed.

If your language is not supported, you can start by copying the en folder and then translating each of the strings to the right of the keywords in the .ftl Fluent files. I’d prefer to have all keys from each file translated in a single commit per language so that we avoid cluttering our commit history with spam, since we also use our commit history as a public human-presentable changelog. If a PR contains multiple languages, it’s necessary to have commits properly named such as i18n(pl): Add Polish translation. I can generally do a squash & merge of drive-by pull requests to a specific language that aren’t formatted correctly though.

As an example, the cosmic-settings repository has its localization files stored here in its i18n directory. You can edit it directly in GitHub while logged into a GitHub account, or fork and clone to make changes locally which you can test.

Git How-To

Some skill with git is necessary. If you wanted to add an Esperanto translation:

• Fork the repository on GitHub to your account
• git clone the URL to your repository
• cd project to move the terminal working directory inside the project
• git checkout -b esperanto to create a new branch named esperanto
• Open the project folder in VS Code and make all your changes (ie: code .)
• git add i18n to add your changes
• git commit -m 'i18n(eo): Add Esperanto translation' to create the commit
• git push origin esperanto to push the changes to your fork
• Use GitHub to create Pull Request from your fork’s branch to our repository

If you made a mistake and want to amend it:

• Make your changes
• git add i18n
• git commit --amend
• Then git push origin esperanto --force
• Your pull request will be automatically updated with the new commit

For a more elaborate PR, use git log to get a history of commits, copy the hash of the commit before where you want to make changes, git rebase -i {hash}, and then you can reorder commits or change pick to e if you want to edit them. Use git commit --amend after completing an edit, and git rebase --continue to reapply all the commits and complete the rebase.

Testing

Either make and run the binary dropped into target/release, or run dpkg-buildpackage -b to build a Debian package. You can run sudo apt build-dep {package-name} to fetch build dependencies for whichever package you’re trying to build. Drops the .deb file(s) in the directory above. Typical dependencies are cargo, libgtk-dev, libssl-dev, and libwebkit2gtk-4.0-dev. Dependencies are listed in the debian/rules file.