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 clonethe URL to your repositorycd projectto move the terminal working directory inside the projectgit checkout -b esperantoto create a new branch namedesperanto- Open the project folder in VS Code and make all your changes (ie:
code .) git add i18nto add your changesgit commit -m 'i18n(eo): Add Esperanto translation'to create the commitgit push origin esperantoto 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 i18ngit 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.