Skip to content

Contributing Translations

Jump to bottom
radj307 edited this page Nov 22, 2023 · 15 revisions

This is intended as an in-depth guide for new translation contributors. It covers the entire process of editing existing translations, creating new ones, forking the repository, and submitting a pull request to get your contribution included in the project.

For more information on translation config syntax & how localization support works, see the documentation for radj307.Localization.

Localization.Editor (WIP)

You can use the Localization.Editor application to edit & create translation configs with a GUI instead of editing the files in a text editor.
It is still in early development. Feedback is appreciated, and can be submitted on the issues page of that repository.

Getting Started

  1. Log in to Github and navigate to the Volume Control repository in your browser.

  2. Click the Fork button.

    The following page will open. Select your Github account under the Owner dropdown box, then click Create Fork.

  3. After a short wait, your forked repository should load.

    If it doesn't open automatically, you can find your fork at this URL:
    https://github.com/<YOUR_GITHUB_USERNAME>/volume-control

  4. When you have your fork of the repo open in your browser, press the period key (./>) to open Github's browser-based version of VS Code.

  5. Take note of the locations of the VolumeControl/Localization & VolumeControl.HotkeyActions/Localization directories.

Before you start writing anything, you should know a bit about how Volume Control's translation configs are structured. Skim through the next section to learn more.

File Format

Directory Description
VolumeControl/Localization Translations for the main application.
VolumeControl.HotkeyActions/Localization Translations for the built-in hotkey actions.

Translation configs are JSON (or YAML) files that contain the translated strings for a language. Don't worry if you aren't familiar with JSON files, you don't actually need to know anything about them to follow this guide.

User-Created Addons can also define translations. This is discussed in more detail in the addon development guide.

File Naming Conventions

Application Translation Configs must be named <LOCALE_ID>.loc.json, where <LOCALE_ID> is the 2-character ISO 639-1 language code of the language defined within that file. You're probably already familiar with the locale ID of your language as you've probably seen it in other places before.
If you're unsure, or just double-checking, you can find the code associated with your language under the 639-1 column of this table on wikipedia.

For example, the locale ID of English is en, so the en.loc.json file contains translations for the English language.

Hotkey Action Translation Configs must be named <LOCALE_ID>-HotkeyActions.loc.json, where <LOCALE_ID> is the same 2-character language code as the one discussed above. This naming convention also applies to translation configs in third-party addons, except HotkeyActions is replaced with the name of the addon assembly.

Translation Keys

A key is a string associated with a value. In the following example, MainWindow is a key, and Hello World! is a value.

"MainWindow": "Hello World!"

Values can be either strings like "Hello World!", or containers with subkeys like in the following example:

"MainWindow": {
  "Text1": "Hello"
  "Text2": "World!"
}

Multiple keys are combined to specify which string to get from a translation config. For example, the value of MainWindow.Text1 is Hello, while the value of MainWindow.Text2 is World!.
When Volume Control requests a translated string, it expects a key with a specific (English) name. The value is what determines the actual text that is displayed.
Do not change the names of keys or Volume Control will not be able to find them!

Translation Config Syntax

Syntax refers to a certain expected pattern of words, symbols, and/or phrases. Volume Control supports 2 different syntaxes in JSON & YAML translation configs:

Single-Language Syntax

Supports 1 language per file, where the language name is determined by the special $LanguageName key. The following example defines a language named English (US/CA) with a single translated string, Hello World!, with the key MainWindow.Text.

{
  "$LanguageName": "English (US/CA)",
  "MainWindow": {
    "Text": "Hello World!"
  }
}

Multi-Language Syntax

More verbose and can support any number of languages in the same file. This example is equivalent to the single-language syntax example:

{
  "MainWindow": {
    "Text": {
      "English (US/CA)": "Hello World!"
    }
  }
}

When using multi-language syntax, special care must be taken to ensure that all of the language name keys are identical. Incorrectly-spelled keys will be interpreted as separate languages.

⚠️ Note

If you choose to use multi-language syntax, do not define multiple languages in the same file! This is to make maintenance easier if something ever needs to be changed in the future.

Debugging Translations

Volume Control can write warning messages to the log when a translation is requested, but couldn't be found for the current language.
To enable this feature, open VolumeControl.json in a text editor and change the following line:

  "LogMissingTranslations": true,

Messages will appear when a translation is displayed in the UI, so if you're debugging a translation that appears on the Settings tab, switch to the Settings tab to trigger the log message. Here's an example of some missing translation log messages:

23:49:38:000  [WARN]      [LocalizationHelper] "English (US/CA)" is missing a translation for key "VolumeControl.ListNotification.Options.FadeIn.Tooltip"
23:49:38:001  [WARN]      [LocalizationHelper] "English (US/CA)" is missing a translation for key "VolumeControl.ListNotification.Options.FadeOut.Tooltip"
                                                ^^^^^^^^^^^^^^^                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                 Language Name                                                   Missing Translation Key

Not all missing translations are a cause for concern, however. The English translation deliberately leaves out some translations for things like certain tooltips & keyboard key names when the additional information isn't needed by English-speaking users. These are available for other languages that may require more context, or have very long words that can interfere with the application's appearance.

Testing Translation Configs

If you want to test a translation config prior to submitting it in a PR, you can have Volume Control load it by editing the config file.

  1. Create a directory to store WIP translation configs, and copy the path (to the directory, not the file(s) in the directory).
  2. Add the path to LocalizationDirectories in VolumeControl.json: 
      "LocalizationDirectories": [
    "X:/Directory/Path"
  ],
  3. Start Volume Control.
    Once a directory has been added to LocalizationDirectories, you don't need to restart VC after making changes to translation configs in that directory. Instead, just click on the Reload button under Settings -> Language.

Note: If you're testing a translation config for a language that is already built in to Volume Control, your custom translation config will be merged with the existing one & overwrite any keys that were already present.

How to Edit an Existing Translation

Open the translation config file (found in VolumeControl/Localization) associated with the translation you want to modify, then proceed to Add a Missing Translated String or Change an Existing Translated String.
Removing a translated string is fairly self-explanatory; simply delete the sections you want to remove from your translation config file.

Add a Missing Translated String

  1. Copy the missing section(s) from en.loc.json and paste it into the correct position(s) in your translation config file.
  2. Change English (US/CA) to your language name using the find & replace tool (CTRL+F ➔ Click on the arrow icon).
  3. Replace the English string(s) with the translated string(s).

Change an Existing Translated String

  1. Find the string you want to change. (CTRL+F)
  2. Replace the string with the new translated string.

How to Create a New Translation

There are 3 main steps to creating a new translation. Each step is described in detail below.

  1. Create a new translation config for the main application.
  2. Create a new translation config for the default hotkey actions.
  3. Mark the new files as embedded resources.

Step 1: Create a new translation config for the main application.

In this step, you'll be translating strings used throughout the application.

  1. Create a new file in the VolumeControl/Localization directory (R+Click ➔ New File).
    Make sure you follow the File Naming Conventions for Application Translation Configs!
  2. Copy the contents of the en.loc.json file into the new file.
  3. Using the find & replace tool (CTRL+F ➔ Click on the arrow icon), search for English (US/CA) and replace it with the name of your language.
  4. Go through each english string and replace it with the equivalent string in your language.

    Make sure you preserve special characters such as newlines (\n), tabs (\t), and macros (${ID}), or the translated string will not appear correctly.
    Some entries also make strategic use of spaces to align text across different lines, for example:
    "Are you sure you want to delete hotkey ${ID}?\n\n- 'Yes' Delete the hotkey.\n- 'No' Do not delete the hotkey.\n- 'Cancel' Don't show this again. (Press again to delete)\n"
    When changing these entries, be sure to use the correct number of spaces to preserve the alignment!

    Some translation strings are not provided in the English translation config because they aren't necessary:
    image
    If you see an empty section, you can add a translation string to it if your language needs additional context for something:
    image

Step 2: Create a new translation config for the default hotkey actions.

In this step, you'll be translating strings used by the default hotkey actions.

  1. Create a new file in the VolumeControl.HotkeyActions/Localization directory (R+Click ➔ New File).
    Make sure you follow the File Naming Conventions for Hotkey Action Translation Configs!
  2. Copy the contents of the en-HotkeyActions.loc.json file into the new file.
  3. Using the find & replace tool (CTRL+F ➔ Click on the arrow icon), search for English (US/CA) and replace it with the name of your language.
  4. Go through each english string and replace it with the equivalent string in your language.

    Again, make sure you preserve special characters such as newlines (\n), tabs (\t), and macros (${ID}), or the translated string will not appear correctly.

Step 3: Mark the new files as embedded resources.

This is the last step in creating a new translation, and it is also the easiest. You need to add 4 lines in 2 different files.

  1. Open VolumeControl/VolumeControl.csproj:
    image-showing-where-VolumeControl.csproj-is
  2. Scroll down to find an <ItemGroup> element with a long list of entries that look like <None Remove="..." />.

    Add a new line at Line #1 in the below image, and type the name of your new translation config file:
    <None Remove="Localization\<LOCALE_ID>.loc.json" />
    Add a new line at Line #2 in the below image, and type the name of your new translation config file again:
    <EmbeddedResource Include="Localization\<LOCALE_ID>.loc.json" />
    image-showing-where-line1-and-line2-are-in-VolumeControl.csproj

  3. Save and close VolumeControl/VolumeControl.csproj.
  4. Open VolumeControl.HotkeyActions/VolumeControl.HotkeyActions.csproj:
    image-showing-where-VolumeControl.HotkeyActions.csproj-is
  5. Again, scroll down to find an <ItemGroup> element with a list of entries that look like <None Remove="..." />

    Add a new line at Line #1 in the below image, and type the name of your new translation config file:
    <None Remove="Localization\<LOCALE_ID>-HotkeyActions.loc.json" />
    Add a new line at Line #2 in the below image, and type the name of your new translation config file again:
    <EmbeddedResource Include="Localization\<LOCALE_ID>-HotkeyActions.loc.json" />
    image-showing-where-line1-and-line2-are-in-VolumeControl.HotkeyActions.csproj

  6. Save and close VolumeControl.HotkeyActions/VolumeControl.HotkeyActions.csproj.

You've successfully created a new translation and embedded it in the application!
All that's left now is to push your changes and submit a pull request.

Push Your Changes

Changes that you make in the editor will not appear in your forked repository until you push them.

  1. Switch to the SOURCE CONTROL tab in the editor.
  2. Enter a brief description of the changes you've made in the Message field, such as "Added support for X language" or "Changed Some.Path to SomeString". This description is relative to whichever file(s) you've edited/created, so keep it brief and don't worry about context.
  3. Click Commit & Push or press CTRL+ENTER to push your changes.

Your forked repository will now contain your changes, and you're ready to submit a pull request.

Submit a Pull Request

Pull Requests (PRs) are Github's way of pushing changes across forked repositories. By submitting a pull request, you can contribute to Volume Control directly, and your Github username and picture (if you have one) will appear in the Contributors section of the main repository:
image

  1. Open https://github.com/radj307/volume-control/pulls in your browser of choice.
  2. Click New pull request.
  3. Click compare across forks.
  4. Change the base repository dropdown box to your fork, then click Create pull request.
  5. Give your PR a name and fill in any relevant information in the description field, then click Create pull request.

You're all done! The developers will review your pull request and merge the changes if everything looks good, otherwise they will ask you to make changes first. For more information, see Updating a Pull Request.

Updating a Pull Request

If the developers ask you to make changes to your pull request before merging it into the main repository, Don't close your existing pull request!
All you have to do to update your existing pull request is push more changes. Your pull request will automatically be updated and no further action is required.

Clone this wiki locally