Translating add-ons

From Official Kodi Wiki
Jump to navigation Jump to search
Home icon grey.png   ▶ Language portal ▶ Translating add-ons

1 Submit your add-on or skin for translation

We encourage all developers with addons in the official Kodi add-on repo to submit their addon for translation at Weblate.

Handling of translations for your add-on will become much more simple, as most things are automated.
Weblate will get updated instantly whenever you add or remove a translation from your source en_gb file.
Translations can be synced to your upstream repository whenever you wish (default is 5 days) either by pull request or direct push.
All languages at Weblate will be kept in sync with the en_gb source file.

Summary, description and disclaimer in addon.xml can be automatically synced between addon.xml and language files either by pull request or direct push whenever changes are made.
See below for more information

We require the following info:

  • URL to your repo at Github/Gitlab
  • Branch
  • Would you like pull requests or direct pushes from Weblate? (Pull requests are safest, direct pushes are easiest.)
  • How often would you like pull requests/direct pushes? Default is 5 days, but it's totally up to you.
  • Do you want a version bump in addon.xml?


For your main source en_gb file to get synced with Weblate, you must add this webhook to your repository for the push event:

https://kodi.weblate.cloud/hooks/github

webhook for Weblate

If direct pushes are wanted, you need to add Github user "weblate" as collaborator.
This user will automatically accept any collaboration within 5 minutes.
If pull requests are the preferred method, Weblate will push to the same pull request until merged or closed.

2 Sync time schedule

Changes to the main source en_gb file are synced instantly from Github to Weblate.
Translations are pushed from Weblate to Github every 5 days (default, but can be configured) if any translations are made.

3 Syntax verification

For keeping the strings correctly formatted, we do a constant syntax verification at all times.
Changes are either done at Weblate or by pull request to the upstream repository.

4 Best practices

  • Only change the content of en_gb source language file.
Never change anything in other language files, as Weblate will handle syncing and maintaining of all strings for all languages.


  • If you have an open Weblate pull request, always merge that pull request before any other.
Failing to do so could result in merge conflicts at Weblate.
Also merge any open Weblate pull request before changing or adding translations to en_gb source file.


  • If doing a minor change for an existing source language (en_gb) string, Weblate will most likely treat this as a completely new string.
That means that all existing translations will get removed for that string.
So be careful before you change existing strings.


  • Sometimes Weblate will add commented out translations at the end of language files.
These should not be removed and are harmless.
They are kept as part of translation memory and will benefit translators in a number of ways.

5 Workflows and scripts

We offer several workflows to help integrate Weblate translations into your add-ons.
Required workflows are automatically offered to your add-on repository by pull request.


5.1 sync-addon-metadata-translations.yml

This workflow will sync metadata (description, summary, disclaimer etc.) between addon.xml and the language files.
It will add this metadata from addon.xml to each language file to allow translation at Weblate.
Whenever changes are done to either addon.xml or any language file, the workflow will run and sync changes both ways.
Either a pull request or direct commit can be created.

An amt-sync branch is created by the workflow where changes are pushed before a pull request is created.
Once the pull request is merged the branch can be safely deleted.
Make sure branch protection is disabled for amt-sync branch and that force pushing is allowed.

This workflow is required for proper Weblate translations.


5.2 increment_version.py

This workflow will bump the version number in your addon.xml file whenever changes are done to the language files.
It can be configured to create a changelog entry as well.
Either a pull request or direct commit can be created.

An inc-ver branch is created by the workflow where changes are pushed before a pull request is created.
Once the pull request is merged the branch can be safely deleted.
Make sure branch protection is disabled for inc-ver branch and that force pushing is allowed.

6 Weblate configuration and add-ons

The text in your Weblate pull request or direct commit can be changed exactly as you see fit.

We enable several add-ons for your component(s) at Weblate.
Most of them will be enabled with default configuration, but some of them can be configured to your preference.


6.1 Squash Git commits

This add-on will squash all Weblate commits into a single one.
But it can also create one commit per language or per file if wanted.


6.2 Customize gettext output

Default for this add-on is to only wrap lines at newlines.
But it can also wrap lines at 77 characters and at newlines or do no line wrapping.