How to Translate

Heads up: There’s a bug!

Translations are not appearing when the application is installed in v0.7.0, but it works when run from the repository folder.

This has been fixed for the next release. Sorry for the inconvenience.


Overview

Polychromatic uses gettext to localize the application to different languages. The source language is English (United Kingdom) for both the interface and code.

Currently, this application’s translation system is decentralised. The translation is performed offline using POT and PO files and is then added into the project’s version control system.


Prerequisites

You’ll need to install:

  • PoeditExternal Link (or other translation editor)
  • The git package (or other Git client)
  • The intltool and gettext package

In order to contribute your changes, you’ll also need:

Before starting, make sure there isn’t an open pull requestExternal Link for your language already. If so, consider leaving a review.

It might be worth checking if there’s been any new, unreleased translations since the last releaseExternal Link.

This guide uses PoeditExternal Link for writing translations and the Terminal for running the git command for version control.


Set up the project

  1. Fork the polychromatic repositoryExternal Link on GitHub.

  2. Clone this repository to your computer.

    git clone https://github.com/<your username>/polychromatic.git
    
  3. Ensure the translation templates are up-to-date.

    ./scripts/create-locales.sh
    
  4. (Optional) If you’ve forked this project before, you may need to reset your repository and obtain the latest changes.

    git reset HEAD --hard
    git pull --rebase https://github.com/polychromatic/polychromatic.git master
    
  5. Check the locales folder for your language’s locale code:

    Translate an existing language Translate for a new language


Translate for a new language

  1. Open locale/polychromatic.pot and click the [Create New Translation] button.

    Screenshot of Poedit after opening pot file

  2. Choose your desired language.

    Language selection screen

  3. Start translating!

    Tip: Enable the sidebar (View → Show Sidebar) to find translator notes for some strings to assist in determining the context.

    Example of translating to Spanish

  4. When finished, save the file to the locales directory.

    Poedit will automatically set the filename to the locale code as appropriate.

    The file name should be the locale code. For example, “Spanish (Spain)” would be saved as es_ES.po.

  5. Open locale/LINGUAS in your text editor and add the new locale code.

  6. Open source/launchers/polychromatic.desktop in your text editor.

    Duplicate these lines:

    • Comment
    • GenericName
    • Name (under Desktop Action)

    Append the locale code before the = sign inside square brackets [] and translate the line, like so:

     GenericName=Device Manager for RGB Lighting
     GenericName[es]=Administrador de dispositivos para iluminación RGB
    
     Comment=Configure connected lighting peripherals
     Comment[es]=Configurar conectado iluminación periféricos
    
     [Desktop Action devices]
     Name=Configure Devices
     Name[es]=Configurar dispositivos
    
  7. (Optional) Test your work to check it looks good for end users.

    Test translation

  8. When you’re happy with your progress, commit/push your changes.

    Commit your changes


Translate for an existing language

Assumes the prerequisites have been followed and that your copy of the repository is up-to-date.

  1. Ensure the translations are up-to-date with the source code.

    ./scripts/create-locales.sh
    
  2. Open PoeditExternal Link and translate!

  3. (Optional) You may wish to check these files too:

    source/launchers/polychromatic.desktop
    
  4. (Optional) Test your work to check it looks good for end users.

    Test translation

  5. When you’re happy with your progress, commit/push your changes.

    Commit your changes


Test a translation

  1. Build the locales:

    ./scripts/build-locales.sh
    
  2. Run the application from the repository, using the --locale parameter to specify the locale code.

    In order to run the main application from the repository folder, some build dependencies may need to be installed. A message will let you know if something is missing.

    ./polychromatic-controller-dev --locale <locale>
    ./polychromatic-tray-applet --locale <locale>
    ./polychromatic-cli --locale <locale>
    

    Note: Only the user interface is translated. Verbose/debugging output in the Terminal remains in English.

  3. When you’re happy with your progress, commit/push your changes.

    Commit your changes


Commit your changes

  1. Open the repository folder in a Terminal. Add the files to Git regarding your locale and create a commit.

    git add locale/<locale>.po
    git add locale/LINGUAS
    git commit -m "Add translation for <locale>"
    

    Note: Please do not add the .pot or .po files for other languages, which are likely to be modified.

  2. Push your commit to your fork (origin)

    git push origin master
    
  3. Open a pull request on GitHub. Use the URL below, and replace GITHUB_USERNAME with your user name.

    https://github.com/GITHUB_USERNAME/polychromatic/compare
    

    Back to top