π₯π₯π₯ Open-source Jira, Linear, Monday, and ClickUp alternative. Plane is a modern project management platform to manage tasks, sprints, docs, and triage.
TypeScript boardsbug-trackerdjangodockerganttissue-trackerjirajira-alternativekanbanlinearpostgresqlproduct-managementproject-managementproject-planningpythonreactredistypesciptvitework-management
Add language translation guidelines (#6639)
Dancia1c6a2fb7dd0c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9d352cbab1..0f5e99cb8e 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -62,17 +62,143 @@ To ensure consistency throughout the source code, please keep these rules in min- All features or bug fixes must be tested by one or more specs (unit-tests).- We use [Eslint default rule guide](https://eslint.org/docs/rules/), with minor changes. An automated formatter is available using prettier.-## Need help? Questions and suggestions--Questions, suggestions, and thoughts are most welcome. We can also be reached in our [Discord Server](https://discord.com/invite/A92xrEGCge).-## Ways to contribute- Try Plane Cloud and the self hosting platform and give feedback- Add new integrations+- Add or update translations- Help with open [issues](https://github.com/makeplane/plane/issues) or [create your own](https://github.com/makeplane/plane/issues/new/choose)- Share your thoughts and suggestions with us- Help create tutorials and blog posts- Request a feature by submitting a proposal- Report a bug- **Improve documentation** - fix incomplete or missing [docs](https://docs.plane.so/), bad wording, examples or explanations.++## Contributing to language support+This guide is designed to help contributors understand how to add or update translations in the application.++### Understanding translation structure++#### File organization+Translations are organized by language in the locales directory. Each language has its own folder containing JSON files for translations. Here's how it looks:++```+packages/i18n/src/locales/+ βββ en/+ β βββ core.json # Critical translations+ β βββ translations.json+ βββ fr/+ β βββ translations.json+ βββ [language]/+ βββ translations.json+```+#### Nested structure+To keep translations organized, we use a nested structure for keys. This makes it easier to manage and locate specific translations. For example:++```json+{+ "issue": {+ "label": "Work item",+ "title": {+ "label": "Work item title"+ }+ }+}+```++### Translation formatting guide+We use [IntlMessageFormat](https://formatjs.github.io/docs/intl-messageformat/) to handle dynamic content, such as variables and pluralization. Here's how to format your translations:++#### Examples+- **Simple variables**+ ```json+ {+ "greeting": "Hello, {name}!"+ }+ ```++- **Pluralization**+ ```json+ {+ "items": "{count, plural, one {Work item} other {Work items}}"+ }+ ```++### Contributing guidelines++#### Updating existing translations+1. Locate the key in `locales/<language>/translations.json`.++2. Update the value while ensuring the key structure remains intact.+3. Preserve any existing ICU formats (e.g., variables, pluralization).++#### Adding new translation keys+1. When introducing a new key, ensure it is added to **all** language files, even if translations are not immediately available. Use English as a placeholder if needed.++2. Keep the nesting structure consistent across all languages.++3. If the new key requires dynamic content (e.g., variables or pluralization), ensure the ICU format is applied uniformly across all languages.++### Adding new languages+Adding a new language involves several steps to ensure it integrates seamlessly with the project. Follow these instructions carefully:++1. **Update type definitions**+Add the new language to the TLanguage type in the language definitions file:++ ```typescript+ // types/language.ts+ export type TLanguage = "en" | "fr" | "your-lang";+ ```++2. **Add language configuration**+Include the new language in the list of supported languages:++ ```typescript+ // constants/language.ts+ export const SUPPORTED_LANGUAGES: ILanguageOption[] = [+ { label: "English", value: "en" },+ { label: "Your Language", value: "your-lang" }+ ];+ ```++3. **Create translation files**+ 1. Create a new folder for your language under locales (e.g., `locales/your-lang/`).++ 2. Add a `translations.json` file inside the folder.++ 3. Copy the structure from an existing translation file and translate all keys.++4. **Update import logic**+Modify the language import logic to include your new language:++ ```typescript+ private importLanguageFile(language: TLanguage): Promise<any> {+ switch (language) {+ case "your-lang":+ return import("../locales/your-lang/translations.json");+ // ...+ }+ }+ ```++### Quality checklist+Before submitting your contribution, please ensure the following:++- All translation keys exist in every language file.+- Nested structures match across all language files.+- ICU message formats are correctly implemented.+- All languages load without errors in the application.+- Dynamic values and pluralization work as expected.+- There are no missing or untranslated keys.++#### Pro tips+- When in doubt, refer to the English translations for context.+- Verify pluralization works with different numbers.+- Ensure dynamic values (e.g., `{name}`) are correctly interpolated.+- Double-check that nested key access paths are accurate.++Happy translating! πβ¨++## Need help? Questions and suggestions++Questions, suggestions, and thoughts are most welcome. We can also be reached in our [Discord Server](https://discord.com/invite/A92xrEGCge).