iobrokertranslator/doc

Documentation of the translation process for ioBroker

Purpose

This repository contains the documentation of the translation process for ioBroker.

Who are you?

• Translator: if you want to help translating ioBroker, please read this document carefully
• Developer: continue reading in this document
• Admin: have a look here as well

Request an adapter to be added to Weblate

If you wish your adapter translations to be managed by Weblate, please ensure the following prerequisites are met and follow the instructions below.

Prerequisites

The following prerequisites must be met before an adapter can be added to Weblate:

• The adapter must contain the i18n files in a separate folder with the default naming scheme

Preparation

1. If the adapter is using gulp, ensure all files are up-to-date by calling gulp translateAndUpdateWordsJS and commit and push those changes to master
2. If the adapter is using @iobroker/adapter-dev, ensure all files are up-to-date by calling npm run translate all and commit and push those changes to master
3. Configure the following repository hook on GitHub
   • Go to the GitHub page of the adapter
   • Click on the "Settings" tab
   • Click on "Webhooks"
   • Click on "Add webhook"
   • Set the Payload URL to https://weblate.iobroker.net/hooks/github/ (everything else can be left as-is)

Request

Please create an issue in requests to add your adapter.

Review translations

Once an administrator has added your adapter, all translations will be marked as "needing action" (except for English). Take time to review all translations that you have done manually or that you feel are OK as they are:

1. Go to https://weblate.iobroker.net/projects/adapters/<your adapter name>/ (e.g. https://weblate.iobroker.net/projects/adapters/tado)
2. Click on a language you translated manually (or that you know well enough to be sure about the translations)
3. Click on "Strings marked for edit"
4. Review the given string and edit it, if needed
5. Uncheck "Needs editing"
6. Click on "Save"
7. Go to step 4. for the next string shown.
8. Once you're done with one language, go to step 1. and choose the next language (if applicable)

Please use "check other occurences" to compare your translation with translations from other adapters. This should lead to consistent translations over all adapters as far as possible.

Add badge to README.md

To show that your adapter is being translated with Weblate, please add the following badge after all other badges to your README.md on GitHub:

[![Translation status](https://weblate.iobroker.net/widgets/adapters/-/<your adapter name>/svg-badge.svg)](https://weblate.iobroker.net/engage/adapters/?utm_source=widget)

Replace <your adapter name> with the name of your adapter (only the part after "ioBroker."). Example:

[![Translation status](https://weblate.iobroker.net/widgets/adapters/-/tado/svg-badge.svg)](https://weblate.iobroker.net/engage/adapters/?utm_source=widget)

Maintenance of your adapter

Don't alter the Git tree

Please never use push --force or any other method that rewrites your default branch. Doing so will immediately lock the translation of the adapter and any pending translations will be lost forever!

Regularly merge pull requests

Once your adapter is connected to Weblate, you will receive automatic pull requests whenever somebody changes texts in Weblate. Please make sure, you merge those pull requests as quickly as possible or at least before committing (or merging) code onto your master or main branch. DO NOT use "Squash and merge" or "Rebase and merge" for Weblate pull requests!

Reason for this is, you will get merge conflicts locally - or even worse on Weblate - if you don't keep your source code up-to-date. Solving merge conflicts locally is possible and in some cases, it solves conflicts in Weblate, but there are cases where you have no choice but to remove all pending changes in Weblate which leads to lost translations.

Adding new translations

It is still possible to edit language files in your project, but it is strongly recommended to do this only for adding and removing strings; not for editing translations.

Whenever you add a new translation string to the source file (en/translations.json) you must ensure all files are up-to-date by calling

• gulp translateAndUpdateWordsJS if the adapter is using gulp
• npm run translate if the adapter is using @iobroker/adapter-dev

and commit and push those changes to master (main). Note that the commands listed above will add new strings to the language files only but not change any existing translation.

Weblate will be updated automatically.

Modifying existing translations

It's strongly recommended to avoid changing existing translations whenever possible. Editing translations locally can cause conflicts with updated translations coming from Weblate. Corrections to any text should be performed inside weblate only.

If you must modify the contents completly and ensure that the change is done in all languages (i.e. if the logic behind a configuration parameter changes and requires a new description) the best way to do this is removing the existing translation and adding a new one with a new key to the english translations.json file. Afterwards the steps described at adding new translations must be executed.

Removing obsolete translations

If you want to remove an outdated translation simply remove the entry from the source file (en/translations.json). Weblate will detect the removed translation and remove the translation at all languages automatically. You should see a PR from weblate after some time (less than one day). Do not forget to merge this PR.

doc's Issues

Weblate PRs with huge number of changes due to whitespace changes

Example:

ioBroker/ioBroker.admin@780d45d

Weblate seems to issue PRs which contain only changes of (leading) whitespaces. I'm quite sure that I did not change anything within admin. I might have browsed admin but not sure either.

Anyway please check whether it would be possible to configure weblate in a way to ignore such whitespace changes.

If the problem ich caused by different settings of nom run translate and weblate formatting, check whether this can be made consistent.

Ignore package-lock.json on PRs

Else npm version on weblate and package-lock version might interfere

Configure Watchtower to respect dependencies on updates

We should shutdown weblate before updating db or cache containers ... so respect the "depends_on" from docker_compose also in watchtower

Weblate small error / enhancement in correction guide

For a merge conflict the following guide is displayed by weblate (here for repo admin)

Typical workflow for fixing merge conflicts

Commit all pending changes in Weblate and lock the translation component.
wlc commit; wlc lock
Add Weblate exported repository as a remote.
git remote add weblate https://weblate.iobroker.net/git/adapters/admin/ ; git remote update weblate
Merge Weblate changes and resolve any conflicts.
git merge weblate/main
Push changes into upstream repository.
git push origin main
Weblate should now be able to see updated repository and you can unlock it.
wlc pull ; wlc unlock
[Check the FAQ for info on how to resolve this.](https://docs.weblate.org/en/weblate-4.12.2/faq.html#merge)

a) instead of or additional to wlc commands hints to the corresponding area at weltae webpage should be given (Users normally do not have access to commandline at weblate system)

b) git merge weblate/main and git push origin main should either use the correct head name (main OR master) or use soe syntax like main/master to guide inexperianced users.

c) In addition please add the following info : (c) UncleSamSwiss Um von Weblate Git pullen zu können, musst du deinen API Key und den Benutzer von Weblate benutzen.

Die Übersetzung wurde automatisch gesperrt, aufgrund folgender Hinweise: Das Repository konnte nicht zusammengeführt werden.

Hi,
iqontrol wurde in weblate gesperrt und ich bekomme es nicht wieder entsperrt. Kann mir jemand dabei helfen?

Fehlermeldung:

Das Repository konnte nicht zusammengeführt werden.
Weblate konnte Upstream-Änderungen während der Aktualisierung des Repositorys nicht zusammenführen.

First, rewinding head to replay your work on top of it...
Applying: Update index_m.js
Using index info to reconstruct a base tree...
M	admin/index_m.js
Falling back to patching base and 3-way merge...
Auto-merging admin/index_m.js
CONFLICT (content): Merge conflict in admin/index_m.js
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch' to see the failed patch
Patch failed at 0001 Update index_m.js

Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".