From 5abc209b9e33d8a3acb4a3d80ddcdb2da841aa8f Mon Sep 17 00:00:00 2001 From: Bertie690 <136088738+Bertie690@users.noreply.github.com> Date: Tue, 10 Jun 2025 11:19:43 -0400 Subject: [PATCH] Create localization.md (WIP) Not done yet but want to save my changes --- docs/localization.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/localization.md diff --git a/docs/localization.md b/docs/localization.md new file mode 100644 index 00000000000..59cbab4073c --- /dev/null +++ b/docs/localization.md @@ -0,0 +1,90 @@ +# Localization 101 + +PokéRogue's localization team puts immense effort into making the game accessible around the world, supporting over 10 different languages at the time of writing this document. +As a developer, it's important to help maintain global accessibility by effectively coordinating with the Translation Team on any new features or enhancements. + +This document aims to cover everything you need to know to help keep the integration process for localization smooth and simple. + +# Basic Assumptions +Before you continue, this document assumes: +- You are familiar with Git commands and GitHub's tools at a basic level. +- You have already set up an environment for development according to the README at https://github.com/pagefaultgames/pokerogue +- You have joined the [community Discord](https://discord.gg/pokerogue) and joined the development channels via **[#select-roles](https://discord.com/channels/1125469663833370665/1194825607738052621)**. +The development channels are the easiest way to keep in touch with the Translation Team and other developers. + +## About the `pokerogue-locales` submodule + +PokéRogue's translations are managed under a dedicated repository at https://github.com/pagefaultgames/pokerogue-locales/. +This repository is integrated into the main repository as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) within the `public/locales` folder. + +### What Is a Submodule? + +In essence, a submodule is a way for one repository (i.e. project) to use another repositoey internally (in this case, locales). +From the perspective of the main project, the locales submodule is fairly simple to work with, but there are some important commands to keep in mind. + +#### Setting Up the Submodule in Your Main Fork + +When you first start development in your main fork, you can fetch translations from the locales repo with this command: +```bash +git submodule update --init --recursive +``` +[^1] +(This step is unnecessary if you ran `git clone` with the `--recurse-submodules` flag as specified in the README.) + +[^1]: If you run into issues with your development environment after doing so, you may have to delete the `.git/modules/public` and `public/locales` folders before re-running the command. +#### Updating Locales to the Latest Version + +When you need to fetch recent locale changes into your working branch, you can do so with this command: + + +```bash +git submodule update --remote --recursive +``` + +(This is run automatically on merge or switching branches, so you _usually_ won't have to run it in most cases. +## Adding Translated Text + +### How Are Translations Integrated? + +This project uses the [i18next library](https://www.i18next.com/) to integrate translations from `public/locales` into the source code based on the user's settings or location. The basic process for fetching translated text is as follows: +1. The source code fetches text by a given key, e.g. + ```ts + i18next.t("fileName:keyName", { arg1: "Hello", arg2: "an example", ... }) + ``` +2. The game looks up the key in the corresponding JSON file in the user's language, e.g. + ```ts + // from "en/file-name.json"... + "keyName": "{{arg1}}! This is {{arg2}} of translated text!" + ``` + If the key doesn't exist for the user's language, the game will default to the corresponding English key. +3. The game shows the text to the user: + ```ts + "Hello! This is an example of translated text!" + ``` + +### Requirements for Adding Translated Text + +If you have a feature or enhancement that requires additions or changes to in-game text, you will need to make a fork of the `pokerogue-locales` repo and submit your text changes as a pull request to that repo _in addition_ to your pull request to the main project. +Since these two PRs aren't technically linked, it's important to coordinate with the Translation Team to ensure that both PRs are integrated safely into the project. +As the developer, you are responsible for creating or adjusting English keys (or your mother language) in support of your feature or enhancement; the Translation Team will take care of the rest. + +When your new feature or enhancement requires a new key **without changing text in existing keys**, we require the following workflow with regards to localization: +1. You (the developer) make a pull request to the main repository for your new feature. If this feature requires new text, the text should be integrated into the code with a new `i18next` key pointing to where you plan to add it into the locales repository. **DO NOT HARDCODE PLAYER-FACING ENGLISH TEXT INTO THE CODE!** +2. You then make another pull request -- this time to the `poketernity-locales` repository -- adding a new entry to the English locale with text for each key you added to your main PR. + - For any feature pulled from the mainline Pokémon games (e.g. a Move or Ability implementation), it's best practice to include a source link for any added text. + [Poké Corpus](https://abcboy101.github.io/poke-corpus/) is a great resource for finding text from the mainline games; otherwise, a video (YouTube or otherwise) showing the text in mainline should suffice. + - You should also notify the current Head of the translation department to ensure a fast response. +3. The Translation Team will approve the locale PR (after corrections, if necessary), then merge it into `pokerogue-locales`. +4. You can then test integration in your main PR after fetching the updated locale (`git submodule update --remote --recursive`). + To ease the review process, you should consider providing a video of any text additions being shown in-game. +6. The Dev Team will approve your main PR for your feature, then merge it into PokéRogue's beta environment. + +### Requirements for Modifying Translated Text + +PRs that modify existing text have different risks with respect to coordination between development and translation, so their requirements are slightly different: +- As above, you set up 2 PRs: one for the feature itself in the main repo, and another for the changes you need to make to the locale repo as a result of your feature. +- Now, however, you need to have your main PR be approved by the Dev Team **before** your corresponding locale changes are merged in. +- After your main PR is approved, the Translation Team will merge your locale PR, and you may update the submodule and post video evidence of locale integration as above. + + +If you have any questions about the developer process for localization, don't hesitate to ask in the PR itself. The Dev Team and Translation Team will be happy to help!