From 06ade9715a68a521055ae910ef56865129e6704e Mon Sep 17 00:00:00 2001 From: Maddy Miller Date: Sat, 27 Dec 2025 14:22:17 +1000 Subject: [PATCH 1/5] Add documentation for localisation --- source/index.rst | 1 + source/localisation.rst | 51 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 source/localisation.rst diff --git a/source/index.rst b/source/index.rst index 25da1b8..44df347 100644 --- a/source/index.rst +++ b/source/index.rst @@ -30,6 +30,7 @@ Documentation api/index faq support + localisation source-code Links diff --git a/source/localisation.rst b/source/localisation.rst new file mode 100644 index 0000000..50c4768 --- /dev/null +++ b/source/localisation.rst @@ -0,0 +1,51 @@ +============ +Localisation +============ + +WorldEdit has inbuilt support for localisation, sourced from community-contributed translations on CrowdIn. These translations are included within WorldEdit releases, so all languages are supported out of the box. WorldEdit uses the language set on each player's Minecraft client to handle translations, so every player will see text in the language that they've defined. + +This means that on multilingual servers, every player can use their preferred language, rather than having to use a single server-defined language. + +How to Contribute +----------------- + +If some parts of WorldEdit aren't fully translated in your language, this usually means that no one has yet submitted a translation. + +We use CrowdIn to facilitate translation submissions, with our CrowdIn page `available here `_. Each time we cut a new WorldEdit release, we verify and pull in the new translations from the website. + +Contributions to our CrowdIn are strongly appreciated, as everyone benefits from better translation coverage. + +Caveats +~~~~~~~ + +At the time of writing, some lines of text relating to command descriptions cannot be translated due to limitations within the command library. Once this is resolved, we'll be sure to add that text into our translation system. + +Custom translations +------------------- + +WorldEdit supports loading user-provided translations, from the ``lang`` folder in the WorldEdit directory. + +When loading languages, a priority system is used to ensure that all available localisation information is loaded. This means that the internal files are loaded first, and then any user provided translations are loaded on top of this. Therefore, if a user provided translation only provided a translation for one single string, it'd still load all of the missing entries from the internal translation data. That way your local copy only needs to contain translations for strings you are explicitly overriding, rather than having to keep it up to date with every WorldEdit release. + +Loading priority occurs in the following order: + +#. ``lang/strings.json`` within the WorldEdit jar file. +#. ``lang/i18n.zip`` within the WorldEdit jar file. +#. ``lang/i18n.zip`` within the WorldEdit folder within the game directory. +#. ``lang/[language-code]`` within the WorldEdit folder within the game directory. + +Due to the way this priority system works, it's recommended to *only* include strings that you are actually intending to modify within your user directories, as that will allow you to automatically benefit from future improvements in later WorldEdit updates. + +.. note:: + + This system is mostly provided to allow you to fill in the gaps of common languages on your Minecraft server, not to fully customise messages. While you can customise messages this way, there are some limits to what can be changed such as an inability to change colours. + +Zip method +~~~~~~~~~~ + +Within your WorldEdit jar file, you'll find a ``lang/i18n.zip`` file. Copying this to ``WorldEdit/lang/i18n.zip`` within your game directory will cause WorldEdit to additionally load from this file. You can modify the contents of the zip file, to have them take a higher priority than the zip file internal to the WorldEdit jar. + +File method +~~~~~~~~~~~ + +Rather than copying the zip file into the ``lang`` folder, you can instead extract it. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en-US``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. From 8634ee148bd07b689a06796ea9599c159800992b Mon Sep 17 00:00:00 2001 From: Maddy Miller Date: Sat, 27 Dec 2025 20:56:51 +1000 Subject: [PATCH 2/5] Replace caveats section with a note --- source/localisation.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/localisation.rst b/source/localisation.rst index 50c4768..35f8f69 100644 --- a/source/localisation.rst +++ b/source/localisation.rst @@ -15,10 +15,9 @@ We use CrowdIn to facilitate translation submissions, with our CrowdIn page `ava Contributions to our CrowdIn are strongly appreciated, as everyone benefits from better translation coverage. -Caveats -~~~~~~~ +.. note:: -At the time of writing, some lines of text relating to command descriptions cannot be translated due to limitations within the command library. Once this is resolved, we'll be sure to add that text into our translation system. + At the time of writing, some lines of text relating to command descriptions cannot be translated due to limitations within the command library. Once this is resolved, we'll be sure to add that text into our translation system. Custom translations ------------------- From 7a8283ff08de79ab65b3d53f6a7410bd9abe2cb3 Mon Sep 17 00:00:00 2001 From: Maddy Miller Date: Tue, 30 Dec 2025 15:47:44 +1000 Subject: [PATCH 3/5] Tweak wording/etc --- source/localisation.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/source/localisation.rst b/source/localisation.rst index 35f8f69..fda1ea4 100644 --- a/source/localisation.rst +++ b/source/localisation.rst @@ -11,7 +11,7 @@ How to Contribute If some parts of WorldEdit aren't fully translated in your language, this usually means that no one has yet submitted a translation. -We use CrowdIn to facilitate translation submissions, with our CrowdIn page `available here `_. Each time we cut a new WorldEdit release, we verify and pull in the new translations from the website. +We use CrowdIn to facilitate translation submissions, with our CrowdIn page `available here `_. Each time we cut a new WorldEdit release, we pull in the new translations from the website. Contributions to our CrowdIn are strongly appreciated, as everyone benefits from better translation coverage. @@ -24,14 +24,16 @@ Custom translations WorldEdit supports loading user-provided translations, from the ``lang`` folder in the WorldEdit directory. -When loading languages, a priority system is used to ensure that all available localisation information is loaded. This means that the internal files are loaded first, and then any user provided translations are loaded on top of this. Therefore, if a user provided translation only provided a translation for one single string, it'd still load all of the missing entries from the internal translation data. That way your local copy only needs to contain translations for strings you are explicitly overriding, rather than having to keep it up to date with every WorldEdit release. +When loading languages, a priority system is used to ensure that all available localisation information is loaded. This is done on a per-string basis, so it's possible for some translations to load from the WorldEdit directory, and others to load from the jar file. Therefore, if a user provided translation only provided a translation for one single string, it'd still load all of the missing entries from the internal translation data. That way your local copy only needs to contain translations for strings you are explicitly overriding, rather than having to keep it up to date with every WorldEdit release. -Loading priority occurs in the following order: +The search order for strings works as follows: -#. ``lang/strings.json`` within the WorldEdit jar file. -#. ``lang/i18n.zip`` within the WorldEdit jar file. -#. ``lang/i18n.zip`` within the WorldEdit folder within the game directory. #. ``lang/[language-code]`` within the WorldEdit folder within the game directory. +#. ``lang/i18n.zip`` within the WorldEdit folder within the game directory. +#. ``lang/i18n.zip`` within the WorldEdit jar file. +#. ``lang/strings.json`` within the WorldEdit jar file. + +If for whatever reason a string in that language cannot be found, it'll repeat the process with a less specific language (eg, ``fr`` instead of ``fr-CA``), and finally fall back to the default language (``en-US``). Due to the way this priority system works, it's recommended to *only* include strings that you are actually intending to modify within your user directories, as that will allow you to automatically benefit from future improvements in later WorldEdit updates. @@ -39,12 +41,14 @@ Due to the way this priority system works, it's recommended to *only* include st This system is mostly provided to allow you to fill in the gaps of common languages on your Minecraft server, not to fully customise messages. While you can customise messages this way, there are some limits to what can be changed such as an inability to change colours. +As a reference for the structure of the files, you can find the ``lang/i18n.zip`` file within the WorldEdit jar file. Any custom translations will follow this same layout, either within a zip file, or in the ``lang`` folder. + Zip method ~~~~~~~~~~ -Within your WorldEdit jar file, you'll find a ``lang/i18n.zip`` file. Copying this to ``WorldEdit/lang/i18n.zip`` within your game directory will cause WorldEdit to additionally load from this file. You can modify the contents of the zip file, to have them take a higher priority than the zip file internal to the WorldEdit jar. +Placing a zip file at ``WorldEdit/lang/i18n.zip`` within your game directory will cause WorldEdit to additionally load from this file. Strings from this zip file will take priority over those within the WorldEdit jar file. File method ~~~~~~~~~~~ -Rather than copying the zip file into the ``lang`` folder, you can instead extract it. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en-US``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. +Rather than using a zip file, you can instead directly store the locale files within folders. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en-US``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. From ef8e7407dd46417c711ec0ff14cc8bee09b73243 Mon Sep 17 00:00:00 2001 From: Maddy Miller Date: Thu, 8 Jan 2026 15:54:52 +1000 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Octavia Togami --- source/localisation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/localisation.rst b/source/localisation.rst index fda1ea4..d1317c0 100644 --- a/source/localisation.rst +++ b/source/localisation.rst @@ -28,12 +28,12 @@ When loading languages, a priority system is used to ensure that all available l The search order for strings works as follows: -#. ``lang/[language-code]`` within the WorldEdit folder within the game directory. -#. ``lang/i18n.zip`` within the WorldEdit folder within the game directory. -#. ``lang/i18n.zip`` within the WorldEdit jar file. -#. ``lang/strings.json`` within the WorldEdit jar file. +#. ``lang/[language-code]/strings.json`` within the WorldEdit folder within the game directory. +#. ``[language-code]/strings.json`` in ``lang/i18n.zip`` within the WorldEdit folder within the game directory. +#. ``[language-code]/strings.json`` in ``lang/i18n.zip`` within the WorldEdit jar file. +#. ``lang/strings.json`` within the WorldEdit jar file (only for the default language). -If for whatever reason a string in that language cannot be found, it'll repeat the process with a less specific language (eg, ``fr`` instead of ``fr-CA``), and finally fall back to the default language (``en-US``). +If for whatever reason a string in that language cannot be found, it'll repeat the process with a less specific language (eg, ``fr`` instead of ``fr-CA``), and finally fall back to the default language (``en``). Due to the way this priority system works, it's recommended to *only* include strings that you are actually intending to modify within your user directories, as that will allow you to automatically benefit from future improvements in later WorldEdit updates. @@ -46,9 +46,9 @@ As a reference for the structure of the files, you can find the ``lang/i18n.zip` Zip method ~~~~~~~~~~ -Placing a zip file at ``WorldEdit/lang/i18n.zip`` within your game directory will cause WorldEdit to additionally load from this file. Strings from this zip file will take priority over those within the WorldEdit jar file. +Placing a zip file at ``WorldEdit/lang/i18n.zip`` within your game directory will cause WorldEdit to load from this file. Strings from this zip file will take priority over those within the WorldEdit jar file. File method ~~~~~~~~~~~ -Rather than using a zip file, you can instead directly store the locale files within folders. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en-US``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. +Rather than using a zip file, you can instead directly store the locale files within folders. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. From 006e77a5cd794bf4a875ef20bc79bb95719629c1 Mon Sep 17 00:00:00 2001 From: Maddy Miller Date: Thu, 8 Jan 2026 16:56:54 +1000 Subject: [PATCH 5/5] Correct Crowdin capitalisation --- source/localisation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/localisation.rst b/source/localisation.rst index d1317c0..94b7087 100644 --- a/source/localisation.rst +++ b/source/localisation.rst @@ -2,7 +2,7 @@ Localisation ============ -WorldEdit has inbuilt support for localisation, sourced from community-contributed translations on CrowdIn. These translations are included within WorldEdit releases, so all languages are supported out of the box. WorldEdit uses the language set on each player's Minecraft client to handle translations, so every player will see text in the language that they've defined. +WorldEdit has inbuilt support for localisation, sourced from community-contributed translations on Crowdin. These translations are included within WorldEdit releases, so all languages are supported out of the box. WorldEdit uses the language set on each player's Minecraft client to handle translations, so every player will see text in the language that they've defined. This means that on multilingual servers, every player can use their preferred language, rather than having to use a single server-defined language. @@ -11,9 +11,9 @@ How to Contribute If some parts of WorldEdit aren't fully translated in your language, this usually means that no one has yet submitted a translation. -We use CrowdIn to facilitate translation submissions, with our CrowdIn page `available here `_. Each time we cut a new WorldEdit release, we pull in the new translations from the website. +We use Crowdin to facilitate translation submissions, with our Crowdin page `available here `_. Each time we cut a new WorldEdit release, we pull in the new translations from the website. -Contributions to our CrowdIn are strongly appreciated, as everyone benefits from better translation coverage. +Contributions to our Crowdin are strongly appreciated, as everyone benefits from better translation coverage. .. note:: @@ -51,4 +51,4 @@ Placing a zip file at ``WorldEdit/lang/i18n.zip`` within your game directory wil File method ~~~~~~~~~~~ -Rather than using a zip file, you can instead directly store the locale files within folders. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from CrowdIn, and instead are written by us when writing the plugin. +Rather than using a zip file, you can instead directly store the locale files within folders. This would mean that Australian English would be in the ``lang/en-AU`` folder, or Greek would be in the ``lang/el`` folder. The "base" translations (``en``) would live in a ``lang/strings.json`` file, rather than having their own directory. This is because they don't come from Crowdin, and instead are written by us when writing the plugin.