mika/pokerogue
1
0
Fork 0
mirror of https://github.com/pagefaultgames/pokerogue.git synced 2025-07-03 23:12:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge 9c09d2cf4d into 2fe50cb761

Browse Source
This commit is contained in:
Bertie690 2025-07-02 15:26:39 -06:00 committed by GitHub
commit 514370a1e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 154 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
CONTRIBUTING.md
View File

@ -2,7 +2,8 @@
Thank you for taking the time to contribute, every little bit helps. This project is entirely open-source and unmonetized - community contributions are what keep it alive! Thank you for taking the time to contribute, every little bit helps. This project is entirely open-source and unmonetized - community contributions are what keep it alive!
Please make sure you understand everything relevant to your changes from the [Table of Contents](#-table-of-contents), and absolutely *feel free to reach out in the **#dev-corner** channel on [Discord](https://discord.gg/pokerogue)*. We are here to help and the better you understand what you're working on, the easier it will be for it to find its way into the game. Please make sure you understand everything relevant to your changes from the [Table of Contents](#-table-of-contents), and absolutely *feel free to reach out in the **#dev-corner** channel on [Discord](https://discord.gg/pokerogue)*.
We are here to help and the better you understand what you're working on, the easier it will be for it to find its way into the game.
## 📄 Table of Contents ## 📄 Table of Contents
@ -11,7 +12,6 @@ Please make sure you understand everything relevant to your changes from the [Ta
- [Getting Started](#-getting-started) - [Getting Started](#-getting-started)
- [Documentation](#-documentation) - [Documentation](#-documentation)
- [Testing Your Changes](#-testing-your-changes) - [Testing Your Changes](#-testing-your-changes)
- [Localization](#-localization)
- [Development Save File (Unlock Everything)](#-development-save-file) - [Development Save File (Unlock Everything)](#-development-save-file)
## 🛠️ Development Basics ## 🛠️ Development Basics
@ -27,16 +27,12 @@ If you have the motivation and experience with Typescript/Javascript (or are wil
- node: >=22.14.0 - [manage with pnpm](https://pnpm.io/cli/env) | [manage with fnm](https://github.com/Schniz/fnm) | [manage with nvm](https://github.com/nvm-sh/nvm) - node: >=22.14.0 - [manage with pnpm](https://pnpm.io/cli/env) | [manage with fnm](https://github.com/Schniz/fnm) | [manage with nvm](https://github.com/nvm-sh/nvm)
- pnpm: 10.x - [how to install](https://pnpm.io/installation) (not recommended to install via `npm` on Windows native) | [alternate method - volta.sh](https://volta.sh/) - pnpm: 10.x - [how to install](https://pnpm.io/installation) (not recommended to install via `npm` on Windows native) | [alternate method - volta.sh](https://volta.sh/)
### Running Locally ### Procedure
1. Clone the repo and in the root directory run `pnpm install` 1. Clone the repo and in the root directory run `pnpm install`
- *if you run into any errors, reach out in the **#dev-corner** channel on Discord* - If you run into any errors, reach out in the **#dev-corner** channel on Discord and someone will be happy to help.
2. Run `pnpm start:dev` to locally run the project at `localhost:8000` 2. Run `pnpm start:dev` to locally run the project at `localhost:8000`
### Linting
Check out our [in-depth file](./docs/linting.md) on linting and formatting!
## 🚀 Getting Started ## 🚀 Getting Started
A great way to develop an understanding of how the project works is to look at test cases (located in [the `test` folder](./test/)). A great way to develop an understanding of how the project works is to look at test cases (located in [the `test` folder](./test/)).
@ -60,8 +56,13 @@ You are free to comment on any issue so that you may be assigned to it and we ca
## 📚 Documentation ## 📚 Documentation
You can find the auto-generated documentation [here](https://pagefaultgames.github.io/pokerogue/main/index.html). You can find the auto-generated documentation [here](https://pagefaultgames.github.io/pokerogue/main/index.html).
For information on enemy AI, check out the [enemy-ai.md](./docs/enemy-ai.md) file.
For detailed guidelines on documenting your code, refer to the [comments.md](./docs/comments.md) file. Additionally, the [docs folder](./docs) contains a variety of in-depth documents and guides useful for aspiring contributors. \
Notable topics include:
- [Commenting your code](./docs/comments.md)
- [Linting & Formatting](./docs/linting.md)
- [Localization](./docs/localization.md)
- [Enemy AI move selection](./docs/enemy-ai.md)
Again, if you have unanswered questions please feel free to ask! Again, if you have unanswered questions please feel free to ask!
@ -101,62 +102,6 @@ Most non-trivial changes (*especially bug fixes*) should come along with new tes
- As much as possible, are unit tests. If you have made two distinct changes, they should be tested in two separate cases. - As much as possible, are unit tests. If you have made two distinct changes, they should be tested in two separate cases.
- Test edge cases. A good strategy is to think of edge cases beforehand and create tests for them using `it.todo`. Once the edge case has been handled, you can remove the `todo` marker. - Test edge cases. A good strategy is to think of edge cases beforehand and create tests for them using `it.todo`. Once the edge case has been handled, you can remove the `todo` marker.
## 📜 Localization
The project intends for all text to be localized. That is, strings are pulled from translation files using keys (depending on the current language) and *never* hardcoded as a particular language. Note that there is a PDF in a message pinned in **#dev-corner** which gives the following information in greater detail.
### Setting Up and Updating the Locales Submodule
> The locales (translation) files are set up as a git submodule. A project-in-a-project, if you will.
To fetch translations when you first start development in your fork or to update them on your local branch, run:
```bash
git submodule update --progress --init --recursive
```
### How Localizations Work
> This project uses the [i18next](https://www.i18next.com/) library 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 (in the case of LATAM Spanish, it will first default to ES Spanish).
3. The game shows the text to the user:
```ts
"Hello! This is an example of translated text!"
```
### Adding Translated Text
> If your feature involves new or modified text in any form, then you will be modifying the [locales](https://github.com/pagefaultgames/pokerogue-locales) repository. ***Never hardcode new text in any language!***
The workflow is:
1. 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 pokerogue-locales repository.
2. Make another pull request -- this time to the [pokerogue-locales](https://github.com/pagefaultgames/pokerogue-locales)
repository -- adding a new entry to the English locale with text for each key
you added to your main PR. You *only* need to add the English key and value - the translation team will handle the rest.
3. If your feature is pulled from the mainline Pokémon games (e.g. a Move or Ability implementation), add a source link for any added text within the locale PR.
[Poké Corpus](https://abcboy101.github.io/poke-corpus) is a great resource for finding text from the latest mainline games; otherwise, a YouTube video link showing the text in mainline is sufficient.
4. Ping @lugiadrien in **#dev-corner** or the current callout thread to make sure your locales PR is seen.
It'll be merged into the locales repository after any necessary corrections, at which point you can test it in your main PR (after updating locales from remote)
5. The Dev team will approve your main PR, and your changes will be in the beta environment!
## 😈 Development Save File ## 😈 Development Save File
> Some issues may require you to have unlocks on your save file which go beyond normal overrides. For this reason, the repository contains a [save file](../test/testUtils/saves/everything.psrv) with _everything_ unlocked (even ones not legitimately obtainable, like unimplemented variant shinies). > Some issues may require you to have unlocks on your save file which go beyond normal overrides. For this reason, the repository contains a [save file](../test/testUtils/saves/everything.psrv) with _everything_ unlocked (even ones not legitimately obtainable, like unimplemented variant shinies).

143
docs/localization.md Normal file
View File

@ -0,0 +1,143 @@
# Localization 101
PokéRogue's localization team puts immense effort into making the game accessible around the world, supporting over 12 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.
# Prerequisites
Before you continue, this document assumes:
- You have already forked the repository and set up a development environment according to [CONTRIBUTING.md](../CONTRIBUTING.md).
- You have a basic level of familiarity with Git commands and GitHub repositories.
- You have joined the [community Discord](https://discord.gg/pokerogue) and have access to `#dev-corner` and related channels via **[#select-roles](https://discord.com/channels/1125469663833370665/1194825607738052621)**.
This is the easiest way to keep in touch with both the Translation Team and other like-minded contributors!
# About the `pokerogue-locales` submodule
PokéRogue's translations are managed under a separate dedicated repository, [`pokerogue-locales`](https://github.com/pagefaultgames/pokerogue-locales/).
This repository is integrated into the main one 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. `pokerogue`) to use another repository (i.e. `pokerogue-locales`) internally.
The parent repo (the "superproject") houses a cloned version of the 2nd repository (the "submodule") inside it, making locales effectively a "repository within a repository", so to speak.
>[!TIP]
> Many popular IDEs have integrated `git` support with special handling around submodules:
> ![Image showing Visual Studio Code's `git` integration in the File Explorer. A blue "S" in the top right hand corner indicates the `public/locales` folder is a submodule.](https://github.com/user-attachments/assets/bd42d354-c65b-4cbe-8873-23d760dc1714 "What the `public/locales` submodule looks like in VS Code's File Explorer")
>
> ![Image showing Visual Studio Code's Source Control tab. A separate dropdown can be seen for each individual submodule.](https://github.com/user-attachments/assets/8b4d3f64-aec1-4474-91df-03dc1252a2fa "Making commits on submodules without even changing directories!")
From the perspective of the main project, the locales submodule is fairly simple to work with.
## Fetching Changes from Submodules
The following command will initialize your branch's locales repository and update its HEAD:
```bash
git submodule update --init --recursive
```
> [!INFO]
> This is run _automatically_ after cloning, merging or changing branches, so you should rarely have to run it manually.
> [!WARNING]
> If you run into issues with the `locales` submodule, try deleting the `.git/modules/public` and `public/locales` folders before re-running the command.
## How Are Translations Integrated?
This project uses the [i18next library](https://www.i18next.com/) to integrate translations from `public/locales` into the source code.
The basic process for fetching translated text goes roughly as follows:
1. The source code fetches text by a given key.
```ts
globalScene.phaseManager.queueMessage(
i18next.t("fileName:keyName", { arg1: "Hello", arg2: "an example", ... })
);
```
2. The game looks up the key in the corresponding JSON file for the user's language.
```jsonc
// from "en/file-name.json"...
{
"keyName": "{{arg1}}! This is {{arg2}} of translated text!"
}
```
If the key doesn't exist for the given language, the game will default to an appropriate fallback (usually the corresponding English key).
3. The game shows the translated text to the user.
```ts
"Hello! This is an example of translated text!"
```
# Submitting Locales Changes
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 _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.
> [!CAUTION]
> **DO NOT HARDCODE PLAYER-FACING TEXT INTO THE CODE!**
## Making Changes
One perk of submodules is you don't actually _need_ to clone the locales repository to start contributing - initializing the submodule already does that for you.
Given `pokerogue-locales` is a full-fledged `git` repository _inside_ `pokerogue`, making changes is roughly the same as normal, merely using `public/locales` as your root directory.
> [!IMPORTANT]
> Make sure to checkout or rebase onto `upstream/HEAD` **BEFORE** creating a PR! \
> The checked-out commit is based on the superproject's SHA-1 by default, so hastily making changes may see you basing your commits on last week's `HEAD`.
## Requirements for Adding Translated Text
When your new feature or enhancement requires adding a new locales 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.
2. You then make another pull request — this time to the `pokerogue-locales` repository — adding a new entry with text for each key you added to your main PR.
- You must add the corresponding **English keys** while making the PR; the Translation Team can take care of the rest[^2].
- 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/picture showing the text being displayed should suffice.
- You should also [notify the current Head of Translation](#notifying-translation) to ensure a fast response.
3. At this point, you may begin [testing locales integration in your main PR](#documenting-locales-changes).
4. The Translation Team will approve the locale PR (after corrections, if necessary), then merge it into `pokerogue-locales`.
5. The Dev Team will approve your main PR for your feature, then merge it into PokéRogue's beta environment.
[^2]: For those wondering, the reason for choosing English specifically is due to it being the master language set in Pontoon (the program used by the Translation Team to perform locale updates).
If a key is present in any language _except_ the master language, it won't appear anywhere else in the translation tool, rendering missing English keys quite a hassle.
### 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 associated locales changes in the locale repo.
- 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 integration into the **locales PR**.
- A Lead or Senior Translator from the Translation Team will then approve your main PR (if all is well), clearing your feature for merging into `beta`.
## Documenting Locales Changes
After making a PR involving any outwards-facing behavior (but _especially_ locales-related ones), it's generally considered good practice to attach proof of those changes working in-game.
The basic procedure is roughly as follows:
1. Update your locales submodule to point to **the branch you used to make the locales PR**. \
Many IDEs with `git` integration support doing this from the GUI, \
or you can simply do it via command-line:
```bash
cd public/locales
git checkout your-branch-name-here
```
2. Set some of the [in-game overrides](../CONTRIBUTING.md#1---manual-testing) inside `overrides.ts` to values corresponding to the interactions being tested.
3. Start a local dev server (`pnpm start:dev`) and open localhost in your browser.
4. Take screenshots or record a video of the locales changes being displayed in-game using the software of your choice[^2].
[^2]: For those lacking a screen capture device, [OBS Studio](https://obsproject.com) is a popular open-source option.
> [!NOTE]
> For those aiming to film their changes, bear in mind that GitHub has a hard **10mB limit** on uploaded media content.
> If your video is too large, consider making it shorter or downscaling the quality.
## Notifying Translation
Put simply, stating that a PR exists makes it much easier to review and merge.
The easiest way to do this is by **pinging the current Head of Translation** in the [community Discord](https://discord.gg/pokerogue) (ideally in `#dev-corner` or similar).
<!-- Remember to update this everytime the head of translation changes! -->
> [!IMPORTANT]
> The current Head of Translation is: \
> ** @lugiadrien **
# Closing Remarks
If you have any questions about the developer process for localization, don't hesitate to ask!
Feel free to contact us on Discord - the Dev Team and Translation Team will be happy to answer any questions.