Skip to content
Sureshpanda20 edited this page Dec 1, 2022 · 6 revisions

Translating Olive

If you'd like to translate Olive to a different language (or contribute to an existing translation), first of all, thank you for helping Olive reach a wider audience! Here are instructions for how to do just that:

Creating/Editing a Translation

  1. You'll need Qt's language tools. Specifically Qt Linguist (linguist) and its accompanying tool lupdate. These can be acquired in many ways depending on your platform (For convenience: Windows, Ubuntu/Mint, Debian, Arch).

  2. Get a copy of the Olive source code, preferably the latest commit. The recommended way to do this is by forking the GitHub repository and then cloning it to your own system. This will allow you to make a GitHub pull request that will make it easy for us to merge it and for you to be credited for writing it.

  3. In a command line, browse to the Olive source code and run the following command:

    lupdate . -ts app/ts/<LOCALE>.ts
    

    Replace <LOCALE> with the locale you're translating to (e.g. app/ts/en_GB.ts for British English or app/ts/pt_BR.ts for Brazilian Portuguese).

    A TS file is where you'll write your translation into. lupdate will either update an existing TS file (preserving already translated strings) or create a new one if it doesn't exist.

    NOTE: In the special case of updating en_US.ts, instruct lupdate to only extract strings that need plural handling with -pluralonly:

    lupdate . -ts app/ts/en_US.ts -pluralonly
    
  4. Browse to app/ts and open the TS file you made in Qt Linguist (linguist). If it's a new TS file, Linguist will ask you for the source and destination language.

    Translation File Settings dialog in Qt Linguist

  5. Set the source language to "English" and country/region to "United States". Then set the target language to the language/country/region you're translating to.

  6. To translate, for each "context" on the left, there will be a set of "source texts" in English. Linguist will also show you the source code that that text appears in to provide better context for each line. In the box below, write your translation in.

    Interface of Qt Linguist

  7. When you're done typing in a translation, press Ctrl+Enter (Cmd+Enter on macOS) to mark it as finished.

For more information about using Qt Linguist, check the official documentation here: https://doc.qt.io/qt-5/linguist-translators.html

Testing your translation

If you'd like to test your translation without recompiling Olive, you can do so by converting your TS to a QM file and providing that to Olive as a command line argument.

  1. To convert your TS file to a QM file, run lrelease, another tool that comes with Qt Linguist:

    lrelease app/ts/en_GB.ts
    

    This will create a new file alongside your TS file called app/ts/en_GB.qm. This is an optimized/compiled version of your TS file that is suitable for running in Olive.

  2. To use it, run Olive with the following command:

    olive-editor --ts <qm-file>
    

    Replacing <qm-file> with the path to the QM file you generated with lrelease.

NOTE: Please don't submit QM files or include them with your pull requests. QM files are generated as part of Olive's compile process so we only need the TS files.

Building your translation into Olive

If you've finished your translation, here are the steps to include it with Olive.

  1. Open app/ts/CMakeLists.txt

  2. Find the section that looks like this:

    set(OLIVE_TS_FILES
      ts/en_GB.ts
      PARENT_SCOPE
    )
    
  3. Add the TS file you generated above the PARENT_SCOPE line. For example, if you created a Brazilian Portuguese translation, your changes should look like this:

    set(OLIVE_TS_FILES
      ts/en_GB.ts
      ts/pt_BR.ts
      PARENT_SCOPE
    )
    

Now Olive should automatically include your translation available in the preferences setting or detected on startup.

Submitting your changes

If you created a fork and are planning to create a pull request, you only need to stage and commit two files:

  • The TS file you created
  • Your changes to app/ts/CMakeLists.txt

If you submit any more files than that, we will likely ask you to remove them from the PR.

Alternatively, we will accept TS files submitted through other channels, however, this is not preferable since it's harder for us to merge it and harder to credit you for your work.