How to Contribute Translations to XWiki

While this post might not contain new information for the veterans of l10n who have been making XWiki available in their native languages for years, I want to share my personal workflow and tips for newcomers. Maybe some points are already known to you, or you might find new things in my detailed approach.

Before diving into the translation work, there are two resources you should keep handy:

• Weblate Documentation: XWiki uses Weblate, an open-source web-based translation platform. It is highly recommended to briefly familiarize yourself with how the tool works by reading the official Weblate Documentation.
• Community Channel: If you encounter any issues, have doubts about context, or face technical difficulties with usage of Weblate platform, please visit the Translations category on the XWiki Forum.

Structure of translations

The translation ecosystem at l10n is divided into four main projects. Understanding these will help you know what part of the software you are influencing:

• XWiki Commons: A set of technical Java libraries that can be reused outside of the XWiki Ecosystem.
• XWiki Rendering: A generic library that functions independently and can be used without the full XWiki Platform.
• XWiki Platform: The generic wiki platform that offers runtime services for applications built on top of it.
• XWiki Contrib: A community dedicated to the collaborative development of XWiki-related projects and extensions in the spirit of wiki communities.

Account setup

To begin, you need an account to contribute, and you have three options:

1. Create a dedicated account on the Weblate platform.
2. Use your existing XWiki.org account.
3. Use your GitHub account.

From my personal experience, I strongly recommend logging in via your GitHub account. Here is why this is the superior choice for a contributor:

• Credit and Attribution: Every translation you make is technically a "commit" to the code. By using GitHub, these contributions are linked directly to your GitHub profile. This means your translation work counts towards your GitHub activity graph, building your public open-source portfolio.
• Streamlined Reviews: For XWiki committers, it is much easier to verify and merge translations when they are linked to a known GitHub user. It simplifies the PR review process.
• Better Communication: If a committer or another translator leaves a comment on your translation PR, GitHub handles the notifications automatically. That's why you won't miss important feedback or questions regarding your contribution.
• Unified Identity: It keeps your development and translation identity in one place, making it easier for the community to recognize you across different XWiki repositories.

How to translate

Before diving in, you might find that the translation for your language has been inactive for a long time or was left unfinished. It do not have to discourage you! This means you have an opportunity to be the one who "revives" the project. You can finally turn the translation to 100% completion for your language. Also, it is always a good idea to check the "History" tab in Weblate. You might discover other currently active translators. In this case, it’s great to coordinate with them to avoid duplicating work and to maintain a consistent translation style.

Once logged in, the first step is to locate your native language (or the language you want to contribute to).

1. From the top menu on the main page, open the "Languages" dropdown and select "Browse all languages|.
2. Find and select your language from the list.
   • For this guide, I will use Ukrainian as an example, as that is where I recently contributed.
3. You will see the project categories (Commons, Rendering, Platform, Contrib). In our example, we can see that XWiki Platform is not yet finished, so let's click on it to see the details.  Note: The statistics will obviously differ for other languages)

Once inside the project (e.g., XWiki Platform), you will see a dashboard with detailed matrix about strings for that project. To find the best place to start:

1. Click on the Components tab.
2. Click on the Translated column header to sort the list. This helps you quickly identify components that are completely untranslated or missing just a few strings.
3. For this example, let's look at the component Mentions UI. We can see it is not translated yet. It is a perfect example how to translate and push it to a platform for a beginner because it contains only one entry (string) consisting of 24 characters.

Create translations and suggestions

Let's click on our chosen untranslated string: "Self Mentions Foreground".

Once inside the translation editor, you generally have two ways to proceed:

• Option A: Direct translation

If you are confident in your translation, you can type it in and click "Save". This immediately commits your translation to the system. After a short delay, Weblate will automatically create a Pull Request in the corresponding GitHub repository (e.g., xwiki-platform/pulls). When you click "Save and Continue", Weblate is designed to keep you in the flow: it will automatically redirect you to the next available untranslated string. If you have just finished the last string in the component, the system will redirect you back to the main component page.

• Option B: Make suggestion

If you are unsure about the wording or context, you can use the "Suggest" button. This does not apply the translation immediately. Instead, it creates a pending suggestion. You (or another contributor) can later review it, edit it if necessary, and finally accept or reject it.

As example here, let's assume we made a suggestion, but we are going to reject/delete it for now. Why? Because simply copy/paste and save the translation based on the text alone isn't good approach. There is a better, more professional workflow how to push translated content.

Editing in IDE and uploading changes to Weblate

While Weblate's interface is great, sometimes you might prefer to work with all strings in once—especially if you want to use a specific text editor and run your own checks before submitting.

Step 1: Download file

1. Go back to the main page of the "Mentions UI" component.
2. Click on the "Files" tab and select "Customize translations".
3. Download the file containing the untranslated strings.

For this example, I chose the TBX format, but you can choose any format that is convenient for your text editor (like CSV, JSON, XML, etc). Be aware that you must understand the specific structure of the file format you choose. You need to know exactly how and where to insert the translated text so that Weblate can import it back correctly. If you are unsure about the file structure, I recommend first downloading a component that is already translated in your desired format. Open it to see exactly how the translations are recorded there, and use that as a reference model for your work.

Step 2: Edit locally

1. Open the downloaded file in your text editor. You will see the code structure.
2. Find the relevant place and insert your translation between the term tags, then save the file. Example, it will be 

   <langSet xml:lang="uk"><tig><term>Тло згадок про себе</term></tig></langSet>

The entire file after changes will be

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE martif PUBLIC "ISO 12200:1999A//DTD MARTIF core (DXFcdV04)//EN" "TBXcdv04.dtd">
<martif type="TBX" xml:lang="en">
    <martifHeader>
        <fileDesc>
            <sourceDesc>
                <p>Translate Toolkit</p>
            </sourceDesc>
        </fileDesc>
    </martifHeader>
    <text>
        <body>
            <termEntry>
                <langSet xml:lang="en"><tig><term>Self Mentions Foreground</term></tig></langSet>
                <langSet xml:lang="uk"><tig><term>Тло згадок про себе</term></tig></langSet>
            </termEntry>
        </body>
    </text>
</martif>

Step 3: Upload updated file

1. Return to the "Customize translations" page on Weblate to upload your modified file.
2. Use these set-up from image

   

3. Click "Upload".

After a while it appears in GitHub, where XWiki committers will review and merge it into main branch, i.e created PR with our changes.

Can't find your language for component?

If you cannot find the component for your target language, it usually means that a translation component for that language has not been created yet. In this case, you need to create the component first. Below image is an example of a non-existent Ukrainian translation for xwiki-platform-security-requiredrights-default component. The newly created component will automatically use the default English content as its initial source. Once the component exists, you can proceed with committing your translation.

Advanced workflow

Translating text in isolation can sometimes lead to not wanted errors because you don't see where the text appears on the screen. Here is how to verify the context using your own running instance of XWiki.

Using Solr to find it in UI

Before translating a new component or entry, you can find it in your personal XWiki instance. Search by translation key you find not only the existing translation document but often the specific UI page or place where that key is used.

Upload screenshots

Weblate allows you to attach images to translation entries. If you find a translation key that has no screenshot, and you have located it in the UI, please take a screenshot. Highlight the area where the text appears and upload it to the entry on Weblate. This way it massively helps future contributors understand the context immediately.

Checks

Even if you are a native speaker and don't rely on auto-translators services or AI bots. By chance you can do wrong pronunciation or mess up sentence structure occasionally. Don't hesitate to run your translated text through a grammar checking tool or a spellchecker. Only push your translation when you are 100% confident in its accuracy.

Stay in the loop

Finally, to ensure you don't miss updates or feedback on your work, make sure your notification settings are set up.

• Go to your profile settings: notifications
• Configure the alerts so you know when strings are updated or when new are added.