Localization Contribution Guidelines
====================================

Thank you for your interest in helping us localize **Blender Development for PyCharm**! Our goal is to make this tool accessible to developers worldwide.

How We Handle Localization (i18n)
---------------------------------

We use the standard IntelliJ Platform internationalization (i18n) mechanism. All user-facing strings (UI labels, tooltips, dialog messages, and log outputs) are stored in ``.properties`` files located in:
``src/main/resources/messages/``

*   **Primary Language (English):** ``LangManager.properties``
*   **Translations:** ``LangManager_<language_code>.properties`` (e.g., ``LangManager_de.properties`` for German).

Currently Supported Languages
-----------------------------

We currently have placeholder or partial translations for the following languages:

*   Spanish (``es``)
*   German (``de``)
*   French (``fr``)
*   Italian (``it``)
*   Japanese (``ja``)
*   Korean (``ko``)
*   Dutch (``nl``)
*   Polish (``pl``)
*   Portuguese (``pt``)
*   Russian (``ru``)
*   Chinese (Simplified) (``zh``)
*   Vietnamese (``vi``)

How to Contribute
-----------------

1. Improve Existing Translations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you see a translation that is incorrect, missing, or sounds unnatural:

1. Locate the corresponding ``LangManager_<code_here>.properties`` file.
2. Find the key you want to change.
3. Update the value (the text after the ``=`` sign).
4. Ensure that any placeholders like ``{0}``, ``{1}`` are preserved and used correctly in the translation.

2. Add a New Language
~~~~~~~~~~~~~~~~~~~~~

If your language is not listed:

1. Create a new file named ``LangManager_<your_language_code>.properties`` in ``src/main/resources/messages/``.
2. Copy the contents of ``LangManager.properties`` into it.
3. Translate the values into your language.

3. Translate New Strings
~~~~~~~~~~~~~~~~~~~~~~~~

When new features are added, new keys appear in the English ``LangManager.properties``. We use automated tools to propagate these keys to other files with English placeholders. You can help by providing the actual translations for these new keys.

Technical Requirements
----------------------

Character Encoding
~~~~~~~~~~~~~~~~~~

*   Property files should use **UTF-8** encoding.
*   Special characters should be handled correctly. IntelliJ IDEA handles this automatically when editing ``.properties`` files.

Placeholders and Escaping
~~~~~~~~~~~~~~~~~~~~~~~~~

*   **Placeholders:** ``{0}``, ``{1}``, etc., are used for dynamic data (like version numbers or file paths). Do not translate or remove these.
*   **Single Quotes:** If you need to use a literal single quote in a message that has placeholders, you must escape it with another single quote (e.g., ``It''s {0}``).

Workflow
--------

1.  **Open an Issue:** (Optional but recommended) Let us know you are working on a specific language to avoid duplicate effort.
2.  **Fork and Branch:** Create a new branch like ``docs/translation-ja``.
3.  **Edit Files:** Make your changes in the ``.properties`` files.
4.  **Verify:** If you have the project set up, run ``./gradlew runIde`` and switch your IDE language (if applicable) to see the changes.
5.  **Pull Request:** Submit your PR with a description of what you improved.

AI Disclosure
-------------

Many of our initial translations were generated with the assistance of LLMs. While helpful, these can often be inaccurate or lack technical context. **Human reviews and corrections are our highest priority!**

----

For more information on the project architecture, see :doc:`../core-concepts/architecture`.