Skip to content

Localising the client

Jump to bottom
Joseph Madamba edited this page Oct 12, 2024 · 11 revisions

Overview

In the osu! client, two types of localisable strings can be distinguished. Some strings are unique and specific to the game client. Others are shared with osu-web, also known as the osu! website - particularly whenever online overlays are concerned, which are supposed to mirror the website content.

Due to this, the flow of propagating new translations is fairly complex, and the correct place to apply a change varies depending on where the string comes from and what language needs to be changed.

Modifying existing strings

Use the following table to determine the correct place to apply your change.

I want to modify an English string I want to modify a string in another language
The string is only used in the client Edit the string in ppy/osu/osu.Game/Localisation Edit the string in the Crowdin osu-web project
The string is shared with osu-web Edit the string in ppy/osu-web/resources/lang/en Edit the string in the Crowdin osu-web project

Localising hardcoded strings

Some strings exclusive to the client may still be unlocalisable since the implementation of LocalisableString and its variants (e.g. LocalisableDescription for enums). They may also be left unlocalisable on recently added features because there is no strict enforcement using LocalisableString yet.

There are some limitations to osu!framework that make it impossible to make some strings localisable at the moment:

For most cases, making a hardcoded string localisable is simple by using the localisation analyser that is integrated into the codebase:

  1. Have the prerequisites for developing osu!.
  2. Do a repo-wide search for the hardcoded string. There will be a dotted underline on the hardcoded string and a light bulb.
  3. Click the light bulb (or Ctrl + .).
  4. Pick an option to put the new localisable string in a new class or common where applicable.
    • Check for existing Strings classes that may fit and move accordingly.
    • Also check for strings that are duplicated and may be classified as common now (i.e. have multiple usages).
    • Localising a sentence may generate an unsuitable property name and key and will need to be renamed.

The following gif shows the process in VSCode:

Localising a string in VSCode

Test the change by running the code and setting the language to Debug (show raw keys) at the bottom and seeing the localisable string in key-value in brackets. If it's not, the drawable may currently be using string and not LocalisableString, and fallbacking to the English string. Using ToString() will also fallback to the English string and not work for other languages.

Technical details of the process

The full flow of translation generation is depicted by the diagram below:

graph TD

client_english[LocalisableString added to<br>ppy/osu/osu.Game/Localisation] -- Exported via ppy/osu-localisation-analyser<br>see: LocalisationAnalyser.Tools to-resx --> client_string_resx_en[New English string resource added to<br>ppy/osu-resources/osu.Game.Resources/Localisation]
client_string_resx_en -- .resx files imported into Crowdin --> crowdin_en[New localisable string added to<br>https://crowdin.com/project/osu-web]
crowdin_en --> crowdin_all[Non-English string localisations<br>contributed on Crowdin by users]
crowdin_all -- client strings: .resx files exported from Crowdin<br><br>web strings: .php files exported from Crowdin<br>and converted via ppy/osu-localisation-analyser to .resx<br>see: LocalisationAnalyser.Tools from-php --> resources_resx_all[All string localisations imported into<br>ppy/osu-resources]
resources_resx_all --> client_consumes[All string localisations consumed by ppy/osu]
web_english[New English string resource added to<br>ppy/osu-web/resources/lang/en] -- .php files imported into Crowdin --> crowdin_en
Loading

The pieces involved in this process are:

  • ppy/osu - the original source of English client-specific strings, and the final consumer of all localisations stored in osu-resources
  • ppy/osu-web - the original source of English strings shared with web
  • ppy/osu-localisation-analyser - hosts LocalisationAnalyser.Tools, which is used in this process twofold:
    • to export English strings from client to .resx files to be uploaded to Crowdin for translation,
    • and to transform .php files with web string translations exported from Crowdin to .resx files
  • the osu-web Crowdin project, which is where users contribute non-English string translations for both client and web
  • ppy/osu-resources, which hosts all .resx files to be finally consumed by the game client

Understanding this process should explain some idiosyncrasies that you may encounter when working on localisations, such as:

  • Q: Why can't I find a string anywhere in the client source?
    • A: If the string isn't English, or is shared with web, then it will not appear in game source. Search Crowdin or osu-resources instead.
Clone this wiki locally