Localization Support

[radj307]

Localization Support (#30)

With the release of v5.2.1, support has been added for UI localization using JSON or YAML language config files.

You can change the UI language at runtime with the Language dropdown, which can be found in the Settings tab.


Note that Process & Device names will always appear as they do in Windows, regardless of the localization settings in the Volume Control app.

You can also change the selected language by editing LanguageName in VolumeControl.json:

  "LanguageName": "English (US/CA)",

Language Configs

A language config is formatted in JSON or YAML, and contains some or all of the strings used by the various parts of the UI.
The structure of these configs is based on the structure of the underlying XAML used by WPF, and is of critical importance; all of the names of the keys must match the translation paths used by the UI.

The language name is used as the key name in language configs, where the value is the translated string.

Format

All language configs start with a LanguageName definition:

  "LanguageName": {
    "English (US/CA)": "English"
  },

These are used to identify the language name, and must be consistent throughout the entire document.
Multiple languages may be defined in the same document, so long as they have different (key) names:

{
  "LanguageName": {
    "English (US/CA)": "English",
    "TestLang": "English"
  },

The rest of the document is composed of objects that represent UI elements.
Each object may contain translation strings or subobjects; but never both. Since there is no way to distinguish between a translation string object and a parent object, it is highly recommended that you use the default language config as a base.

        "TabHeader": {
          "English (US/CA)": "Mixer",
          "TestLang": "rexiM"
        },

Objects that do not have any child objects can be assumed to be translation string objects.

Locations

The default location for language configs is C:\Users\<USERNAME>\AppData\Local\radj307\Localization, additional directories may also be specified using the CustomLocalizationDirectories setting in VolumeControl.json.

VolumeControl.json

There are also some new language settings that can be found in the VolumeControl.json config file:

  "LanguageName": "English (US/CA)",
  "CreateDefaultTranslationFiles": true,
  "CustomLocalizationDirectories": [],

• LanguageName specifies the name of the currently-selected language.
• CreateDefaultTranslationFiles will create the default language configs in the default location when they're missing when set to true.
• CustomLocalizationDirectories is an array of directory paths that language configs will also be loaded from.
  Note that language configs in subdirectories are not loaded!

If you have questions or concerns, post them as a reply to this discussion thread.

[bovirus]

@radj307

Thanks for this new option

Is this master (english) language?

https://github.com/radj307/volume-control/blob/main/VolumeControl/Localization/en.loc.json

The language file xx.loc,.json (wher xx is teh country id - ex it for Italy) should posted in this folder?

https://github.com/radj307/volume-control/tree/main/VolumeControl/Localization

About language name that the user can select whtdo you think to use Local name language and after the English name..Ex

"Italiano (Italian)"

[bovirus]

@radj307

How can set by default to serach .json language file in the same flder where I run Volume Control (to amke it portable)?

[radj307]

You can specify relative paths in CustomLocalizationDirectories.
To load language configs from the current working directory, you would use ".".

By default when you launch the program by double-clicking the executable, or when run at startup is enabled, the working directory is wherever the program is located.
You can also change the working directory with the Start in field in a shortcut, or by running it through a terminal session (see pwd).

[bovirus]

@radj307

I already tried but with default .json config file when I run Volume Control exe with it.loc.json in the same folder teh program didn't detect italian language.
It seems thats teh program search language .json files by default only in user path.

[radj307]

This works for me with v5.2.1 and this in VolumeControl.json:

  "CreateDefaultTranslationFiles": false,
  "CustomLocalizationDirectories": [
    "."
  ],

[bovirus]

@radj307

It's true.
My mention is that with default config.json

"CustomLocalizationDirectories": [],

it didn't work.
I propode you to make as default .json config file now

"CustomLocalizationDirectories": ["."],

Thanks.

[radj307]

The default settings are designed to cause the least amount of unintended side-effects in the majority of use-cases.

Enumerating & attempting to load every file named *.loc.json or *.loc.yaml in the same directory as the executable by default will cause:

• Increased startup time, especially when VolumeControl.exe is located in a directory with many files
• Conflicts with other programs using the same file extensions

The CustomLocalizationDirectories & CustomAddonDirectories settings are intended for the purpose of loading files from non-default locations, adding a default location to them defeats their purpose.

That being said however, I wouldn't be opposed to improving the documentation for this feature so that users know that they can do this; if you have any suggestions as to where to put that, let me know.

[bovirus]

@radj307

Ok. Thanks.
Please add this info for portable use of this appliaction.