Weblate ¶

Processing repository with scripts

Why are all commits committed by Weblate <noreply@weblate.org>?¶

This is the default committer name, configured when you create a translation component. You can also change it in the administration at any time.

The author of every commit (if the underlying VCS supports it) is still recorded correctly as the user who has made the translation.

See also

Component configuration

Usage¶

How do I review others translations?¶

You can subscribe to any changes made in Notifications and then check others contributions in e-mail.
There is a review tool available at the bottom of the translation view, where you can choose to browse translations made by others since a given date.

How do I provide feedback on a source string?¶

On context tabs below translation, you can use the Source tab to provide feedback on a source string or discuss it with other translators.

How can I use existing translations while translating?¶

Weblate provides you with several ways to utilize existing translations while translating:

You can use the import functionality to load compendium as translations, suggestions or translations needing review. This is the best approach for a one time translation using compendium or similar translation database.
You can setup tmserver with all databases you have and let Weblate use it. This is good for cases when you want to use it for several times during translating.
Another option is to translate all related projects in a single Weblate instance, which will make it automatically pick up translations from other projects as well.

Does Weblate update translation files besides translations?¶

Weblate tries to limit changes in translation files to a minimum. For some file formats it might unfortunately lead to reformatting the file. If you want to keep the file formatted in your way, please use a pre-commit hook for that.

For monolingual files (see Supported file formats) Weblate might add new translation strings which are present in the template and not in actual translations. It does not however perform any automatic cleanup of stale strings as that might have unexpected outcomes. If you want to do this, please install a pre-commit hook which will handle the cleanup according to your requirements.

Weblate also will not try to update bilingual files in any way, so if you need po files being updated from pot, you need to do it yourself.

See also

Where do language definitions come from and how can I add my own?¶

The basic set of language definitions is included within Weblate and Translate-toolkit. This covers more than 150 languages and includes information about used plural forms or text direction.

You are free to define own languages in the administrative interface, you just need to provide information about it.

Can Weblate highlight changes in a fuzzy string?¶

Weblate supports this, however it needs the data to show the difference.

For Gettext PO files, you have to pass the parameter --previous to msgmerge when updating PO files, for example:

msgmerge --previous -U po/cs.po po/phpmyadmin.pot

For monolingual translations, Weblate can find the previous string by ID, so it shows the differences automatically.

Why does Weblate still show old translation strings when I’ve updated the template?¶

Weblate does not try to manipulate the translation files in any way other than allowing translators to translate. So it also does not update the translatable files when the template or source code have been changed. You simply have to do this manually and push changes to the repository, Weblate will then pick up the changes automatically.

Note

It is usually a good idea to merge changes done in Weblate before updating translation files, as otherwise you will usually end up with some conflicts to merge.

For example with Gettext PO files, you can update the translation files using the msgmerge tool:

msgmerge -U locale/cs/LC_MESSAGES/django.mo locale/django.pot

In case you want to do the update automatically, you can install addon Update PO files to match POT (msgmerge).

Troubleshooting¶

Requests sometimes fail with too many open files error¶

This happens sometimes when your Git repository grows too much and you have many of them. Compressing the Git repositories will improve this situation.

The easiest way to do this is to run:

# Go to DATA_DIR directory
cd data/vcs
# Compress all Git repositories
for d in */* ; do
    pushd $d
    git gc
    popd
done

See also

DATA_DIR

Fulltext search is too slow¶

Depending on various conditions (frequency of updates, server restarts and other), the fulltext index might become too fragmented over time. It is recommended to optimize it from time to time:

./manage.py rebuild_index --optimize

In case it does not help (or if you have removed a lot of strings) it might be better to rebuild it from scratch:

./manage.py rebuild_index --clean

See also

rebuild_index

I get “Lock Error” quite often while translating¶

This is usually caused by concurrent updates to the fulltext index. In case you are running a multi-threaded server (e.g. mod_wsgi), this happens quite often. For such a setup it is recommended to use Celery to perform updates in the background.

Rebuilding index has failed with “No space left on device”¶

Whoosh uses a temporary directory to build indices. In case you have a small /tmp (eg. using ramdisk), this might fail. Change the temporary directory by passing it as TEMP variable:

TEMP=/path/to/big/temp ./manage.py rebuild_index --clean

See also

rebuild_index

Database operations fail with “too many SQL variables”¶

This can happen when using theSQLite database as it is not powerful enough for some relations used within Weblate. The only way to fix this is to use some more capable database, see Use a powerful database engine for more information.

When accessing the site I get Bad Request (400) error¶

This is most likely caused by an improperly configured ALLOWED_HOSTS. It needs to contain all hostnames you want to access your Weblate. For example:

ALLOWED_HOSTS = ['weblate.example.com', 'weblate', 'localhost']

See also

Allowed hosts setup

Features¶

Does Weblate support other VCS than Git and Mercurial?¶

Weblate currently does not have native support for anything other than Git (with extended support for GitHub, Gerrit and Subversion) and ref:vcs-mercurial, but it is possible to write backends for other VCSes.

You can also use Git remote helpers in Git to access other VCSes.

Weblate also supports VCS less operation, see Local files.

Note

For native support of other VCS, Weblate requires distributed VCS and could be probably adjusted to work with anything other than Git and Mercurial, but somebody has to implement this support.

See also

Version control integration

How does Weblate credit translators?¶

Every change made in Weblate is committed into VCS under the translators name. This way every single change has proper authorship and you can track it down using standard VCS tools you use for code.

Additionally, when the translation file format supports it, the file headers are updated to include the translator name.

See also

list_translators

Why does Weblate force to show all po files in a single tree?¶

Weblate was designed in a way that every po file is represented as a single component. This is beneficial for translators, so they know what they are actually translating. If you feel your project should be translated as one, consider merging these po files. It will make life easier even for translators not using Weblate.

Note

In case there will be big demand for this feature, it might be implemented in future versions, but it’s definitely not a priority for now.

Why does Weblate use language codes such sr_Latn or zh_Hant?¶

These are language codes defined by RFC 4646 to better indicate that they are really different languages instead previously wrongly used modifiers (for @latin variants) or country codes (for Chinese).

Weblate will still understand legacy language codes and will map them to current one - for example sr@latin will be handled as sr_Latn or zh@CN as sr_Hans.

Supported file formats¶

Weblate supports most translation format understood by the translate-toolkit, however each format being slightly different, there might be some issues with formats that are not well tested.

See also

Translation Related File Formats

Note

When choosing a file format for your application, it’s better to stick some well established format in the toolkit/platform you use. This way your translators can use whatever tools they are get used to and will more likely contribute to your project.

Bilingual and monolingual formats¶

Weblate does support both monolingual and bilingual formats. Bilingual formats store two languages in single file - source and translation (typical examples are GNU Gettext, XLIFF or Apple iOS strings). On the other side, monolingual formats identify the string by ID and each language file contains only mapping of those to given language (typically Android string resources). Some file formats are used in both variants, see detailed description below.

For correct use of monolingual files, Weblate requires access to a file containing complete list of strings to translate with their source - this file is called Monolingual base language file within Weblate, though the naming might vary in your application.

Automatic detection¶

Weblate can automatically detect several widely spread file formats, but this detection can harm your performance and will limit features specific to given file format (for example automatic adding of new translations).

Translation types capabilities¶

Below are listed capabilities of all supported formats.

Format	Linguality [1]	Plurals [2]	Comments [3]	Context [4]	Location [5]	Flags [8]	Additional states [6]
GNU Gettext	bilingual	yes	yes	yes	yes	yes [9]	needs editing
Monolingual Gettext	mono	yes	yes	yes	yes	yes [9]	needs editing
XLIFF	both	yes	yes	yes	yes	yes [10]	needs editing, approved
Java properties	both	no	yes	no	no	no
Joomla translations	mono	no	yes	no	yes	no
Qt Linguist .ts	both	yes	yes	no	yes	yes [10]	needs editing
Android string resources	mono	yes	yes [7]	no	no	yes [10]
Apple iOS strings	bilingual	no	yes	no	no	no
PHP strings	mono	no	yes	no	no	no
JSON files	mono	no	no	no	no	no
JSON i18next files	mono	yes	no	no	no	no
WebExtension JSON	mono	yes	yes	no	no	no
.NET Resource files	mono	no	yes	no	no	yes [10]
CSV files	mono	no	yes	yes	yes	no	needs editing
YAML files	mono	no	yes	no	no	no
Ruby YAML files	mono	yes	yes	no	no	no
DTD files	mono	no	no	no	no	no
Windows RC files	mono	no	yes	no	no	no
Excel Open XML	mono	no	yes	yes	yes	no	needs editing
App store metadata files	mono	no	no	no	no	no
Subtitle files	mono	no	no	no	yes	no

[1]	See Bilingual and monolingual formats

[2]	Plurals are necessary to properly localize strings with variable count.

[3]	Comments can be used to pass additional information about string to translate.

[4]	Context is used to differentiate same strings used in different scope (eg. Sun can be used as abbreviated name of day or as a name of our closest star).

[5]	Location of string in source code might help skilled translators to figure out how the string is used.

[6]	Additional states supported by the file format in addition to not translated and translated.

[7]	XML comment placed before the `<string>` element is parsed as a developer comment.

[8]	See Customizing behavior

[9]	(1, 2) The Gettext type comments are used as flags.

[10]	(1, 2, 3, 4) The flags are extracted from non standard attibute `weblate-flags` for all XML based formats. Additionally `max-length:N` is supported through `maxwidth` attribute as defined in the Xliff standard.

GNU Gettext¶

Most widely used format in translating free software. This was first format supported by Weblate and still has the best support.

Weblate supports contextual information stored in the file, adjusting its headers or linking to corresponding source files.

The bilingual gettext PO file typically looks like:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "Monday"
msgstr "Pondělí"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "Tuesday"
msgstr "Úterý"

#: weblate/accounts/avatar.py:163
msgctxt "No known user"
msgid "None"
msgstr "Žádný"

Typical Weblate Component configuration
File mask	`po/*.po`
Monolingual base language file	Empty
Template for new translations	`po/messages.pot`
File format	Gettext PO file

Monolingual Gettext¶

Some projects decide to use Gettext as monolingual formats - they code just IDs in their source code and the string needs to be translated to all languages, including English. Weblate does support this, though you have to choose explicitly this file format when importing components into Weblate.

The monolingual gettext PO file typically looks like:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-monday"
msgstr "Pondělí"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-tuesday"
msgstr "Úterý"

#: weblate/accounts/avatar.py:163
msgid "none-user"
msgstr "Žádný"

While the base language file will be:

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-monday"
msgstr "Monday"

#: weblate/media/js/bootstrap-datepicker.js:1421
msgid "day-tuesday"
msgstr "Tuesday"

#: weblate/accounts/avatar.py:163
msgid "none-user"
msgstr "None"

Typical Weblate Component configuration
File mask	`po/*.po`
Monolingual base language file	`po/en.po`
Template for new translations	`po/messages.pot`
File format	Gettext PO file (monolingual)

XLIFF¶

XML-based format created to standardize translation files, but in the end it is one of many standards in this area.

XLIFF is usually used as bilingual, but Weblate supports it as monolingual as well.

Translations states¶

Changed in version 3.3: Weblate did ignore the state attribute prior to the 3.3 release.

The state attribute in the file is partially processed and mapped to needs edit state in Weblate (the following states are used to flag the string as needing edit if there is some target present: new, needs-translation, needs-adaptation, needs-l10n). Should the state attribute be missing a string is considered translated as soon as a <target> element exists.

Also if the translation string has approved="yes" it will be imported into Weblate as approved, anything else will be imported as waiting for review (which matches XLIFF specification).

That means that when using XLIFF format, it is strongly recommended to enable Weblate review process, in order to see and change the approved state of strings. See Dedicated reviewers.

Similarly on importing such files, you should choose Import as translated under Processing of strings needing review.

Whitespace and newlines in XLIFF¶

Generally the XML formats do not differentiate between types or amounts of whitespace. If you want to keep it, you have to add the xml:space="preserve" flag to the string.

For example:

    <trans-unit id="10" approved="yes">
        <source xml:space="preserve">hello</source>
        <target xml:space="preserve">Hello, world!
</target>
    </trans-unit>

Specifying translation flags¶

You can specify additional translation flags (see Customizing behavior) in using weblate-flags attribute. Weblate also understands maxwidth attribute from the Xliff specification:

<trans-unit id="10" maxwidth="100" weblate-flags="c-format">
   <source>Hello %s</source>
</trans-unit>

Typical Weblate Component configuration for bilingual XLIFF
File mask	`localizations/*.xliff`
Monolingual base language file	Empty
Template for new translations	`localizations/en-US.xliff`
File format	XLIFF Translation File

Typical Weblate Component configuration for monolingual XLIFF
File mask	`localizations/*.xliff`
Monolingual base language file	`localizations/en-US.xliff`
Template for new translations	`localizations/en-US.xliff`
File format	XLIFF Translation File

See also

XLIFF on Wikipedia, XLIFF

Java properties¶

Native Java format for translations.

Java properties are usually used as monolingual.

Weblate supports ISO-8859-1, UTF-8 and UTF-16 variants of this format. All of them supports storing all Unicode characters, it’s just differently encoded. In the ISO-8859-1 the Unicode escape sequences are used (eg. zkou\u0161ka), all others encode characters directly either in UTF-8 or UTF-16.

Note

Loading of escape sequences will work in UTF-8 mode as well, so please be careful choosing correct charset matching your application needs.

Typical Weblate Component configuration
File mask	`src/app/Bundle_*.properties`
Monolingual base language file	`src/app/Bundle.properties`
Template for new translations	Empty
File format	Java Properties (ISO-8859-1)

Joomla translations¶

New in version 2.12.

Native Joomla format for translations.

Joomla translations are usually used as monolingual.

Typical Weblate Component configuration
File mask	`language/*/com_foobar.ini`
Monolingual base language file	`language/en-GB/com_foobar.ini`
Template for new translations	Empty
File format	Joomla Language File

Qt Linguist .ts¶

Translation format used in Qt based applications.

Qt Linguist files are used as both bilingual and monolingual.

Typical Weblate Component configuration when using as bilingual
File mask	`i18n/app.*.ts`
Monolingual base language file	Empty
Template for new translations	`i18n/app.de.ts`
File format	Qt Linguist Translation File

Typical Weblate Component configuration when using as monolingual
File mask	`i18n/app.*.ts`
Monolingual base language file	`i18n/app.en.ts`
Template for new translations	`i18n/app.en.ts`
File format	Qt Linguist Translation File

Android string resources¶

Android specific file format for translating applications.

Android string resources are monolingual, the Monolingual base language file file is stored in a different location from the others res/values/strings.xml.

Typical Weblate Component configuration
File mask	`res/values-*/strings.xml`
Monolingual base language file	`res/values/strings.xml`
Template for new translations	Empty
File format	Android String Resource

Note

Android string-array structures are not currently supported. To work around this, you can break you string arrays apart:

<string-array name="several_strings">
    <item>First string</item>
    <item>Second string</item>
</string-array>

become:

<string-array name="several_strings">
    <item>@string/several_strings_0</item>
    <item>@string/several_strings_1</item>
</string-array>
<string name="several_strings_0">First string</string>
<string name="several_strings_1">Second string</string>

The string-array that points to the string elements should be stored in a different file, and not localized.

This script may help pre-process your existing strings.xml files and translations: https://gist.github.com/paour/11291062

Apple iOS strings¶

Apple specific file format for translating applications, used for both iOS and iPhone/iPad application translations.

Apple iOS strings are usually used as bilingual.

Typical Weblate Component configuration
File mask	`Resources/*.lproj/Localizable.strings`
Monolingual base language file	`Resources/en.lproj/Localizable.strings`
Template for new translations	Empty
File format	iOS Strings (UTF-8)

PHP strings¶

PHP translations are usually monolingual, so it is recommended to specify base file with English strings.

Example file:

<?php
$LANG['foo'] = 'bar';
$LANG['foo1'] = 'foo bar';
$LANG['foo2'] = 'foo bar baz';
$LANG['foo3'] = 'foo bar baz bag';

Typical Weblate Component configuration
File mask	`lang/*/texts.php`
Monolingual base language file	`lang/en/texts.php`
Template for new translations	`lang/en/texts.php`
File format	PHP strings

Note

Translate-toolkit currently has some limitations in processing PHP files, so please double check that your files won’t get corrupted before using Weblate in production setup.

Following things are known to be broken:

Adding new strings to translation, every translation has to contain all strings (even if empty).
Handling of special chars like newlines.

See also

PHP

JSON files¶

New in version 2.0.

Changed in version 2.16: Since Weblate 2.16 and with translate-toolkit at least 2.2.4 nested structure JSON files are supported as well.

JSON format is used mostly for translating applications implemented in JavaScript.

Weblate currently supports several variants of JSON translations:

Simple key / value files.
Files with nested keys.
JSON i18next files
WebExtension JSON

JSON translations are usually monolingual, so it is recommended to specify base file with English strings.

Example file:

{
    "Hello, world!\n": "Ahoj světe!\n",
    "Orangutan has %d banana.\n": "",
    "Try Weblate at https://demo.weblate.org/!\n": "",
    "Thank you for using Weblate.": ""
}

Nested files are supported as well (see above for requirements), such file can look like:

{
    "weblate": {
        "hello": "Ahoj světe!\n",
        "orangutan": "",
        "try": "",
        "thanks": ""
    }
}

Typical Weblate Component configuration
File mask	`langs/translation-*.json`
Monolingual base language file	`langs/translation-en.json`
Template for new translations	Empty
File format	JSON nested structure file

JSON i18next files¶

Changed in version 2.17: Since Weblate 2.17 and with translate-toolkit at least 2.2.5 i18next JSON files with plurals are supported as well.

i18next is an internationalization-framework written in and for JavaScript. Weblate supports its localization files with features such as plurals.

i18next translations are monolingual, so it is recommended to specify base file with English strings.

Note

Weblate supports i18next JSON v3 format. The v2 and v1 variants are mostly compatible, with exception of handling plurals.

Example file:

{
  "hello": "Hello",
  "apple": "I have an apple",
  "apple_plural": "I have {{count}} apples",
  "apple_negative": "I have no apples"
}

Typical Weblate Component configuration
File mask	`langs/*.json`
Monolingual base language file	`langs/en.json`
Template for new translations	Empty
File format	i18next JSON file

WebExtension JSON¶

New in version 2.16: This is supported since Weblate 2.16 and with translate-toolkit at least 2.2.4.

File format used when translating extensions for Google Chrome or Mozilla Firefox.

Example file:

{
    "hello": {
        "message": "Ahoj světe!\n",
        "description": "Description"
    },
    "orangutan": {
        "message": "",
        "description": "Description"
    },
    "try": {
        "message": "",
        "description": "Description"
    },
    "thanks": {
        "message": "",
        "description": "Description"
    }
}

Typical Weblate Component configuration
File mask	`_locales/*/messages.json`
Monolingual base language file	`_locales/en/messages.json`
Template for new translations	Empty
File format	WebExtension JSON file

.NET Resource files¶

New in version 2.3.

.NET Resource (.resx) file is a monolingual XML file format used in Microsoft .NET Applications. It works with .resw files as well as they use identical syntax to .resx.

Typical Weblate Component configuration
File mask	`Resources/Language.*.resx`
Monolingual base language file	`Resources/Language.resx`
Template for new translations	Empty
File format	.NET resource file

CSV files¶

New in version 2.4.

CSV files can contain a simple list of source and translation. Weblate supports the following files:

Files with header defining fields (source, translation, location, …). This is recommended approach as it’s least error prone.
Files with two fields - source and translation (in this order), choose Simple CSV file as file format
Files with fields as defined by translate-toolkit: location, source, target, id, fuzzy, context, translator_comments, developer_comments

Warning

The CSV format currently automatically detects dialect of the CSV file. In some cases the automatic detection might fail and you will get mixed results. This is especially true for the CSV files with newlines in the values. As a workaround it is recommended to avoid omitting quoting chars.

Example file:

Thank you for using Weblate.,Děkujeme za použití Weblate.

Typical Weblate Component configuration
File mask	`locale/*.csv`
Monolingual base language file	Empty
Template for new translations	`locale/en.csv`
File format	CSV file

See also

CSV

YAML files¶

New in version 2.9.

The plain YAML files with string keys and values.

Example YAML file:

weblate:
  hello: ""
  orangutan": ""
  try": ""
  thanks": ""

Typical Weblate Component configuration
File mask	`translations/messages.*.yml`
Monolingual base language file	`translations/messages.en.yml`
Template for new translations	Empty
File format	YAML file

See also

YAML, Ruby YAML files

Ruby YAML files¶

New in version 2.9.

Ruby i18n YAML files with language as root node.

Example Ruby i18n YAML file:

cs:
  weblate:
    hello: ""
    orangutan: ""
    try: ""
    thanks: ""

Typical Weblate Component configuration
File mask	`translations/messages.*.yml`
Monolingual base language file	`translations/messages.en.yml`
Template for new translations	Empty
File format	Ruby YAML file

See also

YAML, YAML files

DTD files¶

New in version 2.18.

Example DTD file:

<!ENTITY hello "">
<!ENTITY orangutan "">
<!ENTITY try "">
<!ENTITY thanks "">

Typical Weblate Component configuration
File mask	`locale/*.dtd`
Monolingual base language file	`locale/en.dtd`
Template for new translations	Empty
File format	DTD file

See also

Mozilla DTD format

Windows RC files¶

New in version 3.0: Experimental support has been added in Weblate 3.0, not supported on Python 3.

Example Windows RC file:

LANGUAGE LANG_CZECH, SUBLANG_DEFAULT

STRINGTABLE DISCARDABLE
BEGIN

IDS_MSG1 "Hello, world!\n"
IDS_MSG2 "Orangutan has %d banana.\n"
IDS_MSG3 "Try Weblate at http://demo.weblate.org/!\n"
IDS_MSG4 "Thank you for using Weblate."
END

Typical Weblate Component configuration
File mask	`lang/*.rc`
Monolingual base language file	`lang/en-US.rc`
Template for new translations	`lang/en-US.rc`
File format	RC file

See also

Windows RC files

App store metadata files¶

New in version 3.5.

Weblate can translate metadata used for publishing apps in various app stores. Currently it is known to be compatible with following tools:

The metadata consist of several text files which Weblate will present as separate strings to translate.

Typical Weblate Component configuration
File mask	`fastlane/android/metadata/*`
Monolingual base language file	`fastlane/android/metadata/en-US`
Template for new translations	`fastlane/android/metadata/en-US`
File format	App store metadata files

Subtitle files¶

New in version 3.7.

Weblate can translate various subtile files:

SubRip subtitle file (*.srt)
MicroDVD subtitles file (*.sub)
Advanced Substation Alpha subtitles file (*.ass)
Substation Alpha subtitles file (*.ssa)

Typical Weblate Component configuration
File mask	`path/*.srt`
Monolingual base language file	`path/en.srt`
Template for new translations	`path/en.srt`
File format	SubRip subtitle file

See also

Subtitles

Excel Open XML¶

New in version 3.2.

Weblate can import and export Excel Open XML (xlsx) files.

When using xlsx files for translation upload, be aware that only the active worksheet is considered and there must be at least a column called source (which contains the source string) and a column called target (which contains the translation). Additionally there should be the column context (which contains the context path of the translation string). If you use the xlsx download for exporting the translations into an Excel workbook, you already get a file with the correct file format.

Others¶

Most formats supported by translate-toolkit which support serializing can be easily supported, but they did not (yet) receive any testing. In most cases some thin layer is needed in Weblate to hide differences in behavior of different translate-toolkit storages.

See also

Translation Related File Formats

Adding new translations¶

Changed in version 2.18: In versions prior to 2.18 the behaviour of adding new translations was file format specific.

Weblate can automatically start new translation for all of the file formats.

Some formats expect to start with empty file and only translated strings to be included (eg. Android string resources), while others expect to have all keys present (eg. GNU Gettext). In some situations this really doesn’t depend on the format, but rather on framework you use to handle the translation (eg. with JSON files).

When you specify Template for new translations in Component configuration, Weblate will use this file to start new translations. Any exiting translations will be removed from the file when doing so.

When Template for new translations is empty and file format supports it, empty file is created where new strings will be added once they are translated.

The Language code style allows you to customize language code used in generated filenames:

Default based on the file format: Dependent on file format, for most of them POSIX is used.
POSIX style using underscore as a separator: Typically used by Gettext and related tools, produces language codes like pt_BR.
BCP style using hyphen as a separator: Typically used on web platforms, produces language codes like pt-BR.
Android style: Used only on Android apps, produces language codes like pt-rBR.

Note

Weblate recognizes any of these when parsing translation files, the above settings only influences how new files are created.

Version control integration¶

Weblate currently supports Git (with extended support for GitHub, Gerrit and Subversion) and Mercurial as version control backends.

Accessing repositories¶

The VCS repository you want to use has to be accessible to Weblate. With a publicly available repository you just need to enter correct URL (for example git://github.com/WeblateOrg/weblate.git or https://github.com/WeblateOrg/weblate.git), but for private repositories the setup might be more complex.

Weblate internal URLs¶

To share one repository between different components you can use a special URL like weblate://project/component. This way, the component will share the VCS repository configuration with referenced component and the VCS repository will be stored just once on the disk.

SSH repositories¶

The most frequently used method to access private repositories is based on SSH. To have access to such a repository, you generate SSH key for Weblate and authorize it to access the repository. Weblate also needs to know the host key to avoid man in the middle attacks. This all can be done in the Weblate administration interface:

Generating SSH keys¶

You can generate or display the key currently used by Weblate in the admin interface (follow SSH keys link on main admin page). Once you’ve done this, Weblate should be able to access your repository.

Note

The keys need to be without password to make it work, so be sure they are well protected against malicious usage.

Warning

On GitHub, you can add the key to only one repository. See the following sections for other solutions for GitHub.

Verifying SSH host keys¶

Before connecting to the repository, you also need to verify SSH host keys of servers you are going to access in the same section of the admin interface. You can do this in the Add host key section. Just enter hostname you are going to access (eg. gitlab.com) and press Submit. After adding it please verify that the fingerprint matches the server you’re adding, the fingerprints will be displayed in the confirmation message:

HTTPS repositories¶

To access protected HTTPS repositories, you need to include the username and password in the URL. Don’t worry, Weblate will strip this information when showing the URL to the users (if they are allowed to see the repository URL at all).

For example the GitHub URL with authentication might look like https://user:your_access_token@github.com/WeblateOrg/weblate.git.

Note

In case your username or password contains special chars, those have to be URL encoded, for example https://user%40example.com:%24password%23@bitbucket.org/...`.

Using proxy¶

If you need to access http/https VCS repositories using a proxy server, you need to configure the VCS to use it.

This can be configured using the http_proxy, https_proxy, and all_proxy environment variables (check cURL documentation for more details) or by enforcing it in VCS configuration, for example:

git config --global http.proxy http://user:password@proxy.example.com:80

Note

The proxy setting needs to be done in the same context which is used to execute Weblate. For the environment it should be set for both wsgi and Celery servers. The VCS configuration has to be set for the user which is running Weblate.

See also

curl manpage, git config documentation

Git¶

Git is first VCS backend that was available in Weblate and is still the most stable and tested one.

See also

See Accessing repositories for information how to access different kind of repositories.

GitHub repositories¶

You can access GitHub repositories by SSH as mentioned above, but in case you need to access more repositories, you will hit a GitHub limitation on the SSH key usage (one key can be used only for one repository). There are several ways to work around this limitation.

For smaller deployments, you can use HTTPS authentication using a personal access token and your account, see Creating an access token for command-line use.

For a bigger setup, it is usually better to create dedicated user for Weblate, assign him the SSH key generated in Weblate and grant him access to all repositories you want.

Customizing Git configuration¶

Weblate invokes all VCS commands with HOME pointed to home directory in DATA_DIR, therefore if you want to edit user configuration, you need to do this in DATA_DIR/home/.git.

Git remote helpers¶

You can also use Git remote helpers for supporting other VCS as well, but this usually leads to other problems, so be prepared to debug them.

At this time, helpers for Bazaar and Mercurial are available within separate repositories on GitHub: git-remote-hg and git-remote-bzr. You can download them manually and put somewhere in your search path (for example ~/bin). You also need to have installed appropriate version control programs as well.

Once you have these installed, you can use such remotes to specify repository in Weblate.

To clone gnuhello project from Launchpad with Bazaar use:

bzr::lp:gnuhello

For hello repository from selenic.com with Mercurial use:

hg::http://selenic.com/repo/hello

Warning

Please be prepared to some inconvenience when using Git remote helpers, for example with Mercurial, the remote helper sometimes tends to create new tip when pushing changes back.

GitHub¶

New in version 2.3.

This just adds a thin layer on top of Git to allow push translation changes as pull requests instead of pushing directory to the repository. It currently uses the hub tool to do the integration.

There is no need to use this to access Git repositories, ordinary Git works the same, the only difference is how pushing to a repository is handled. With Git changes are pushed directly to the repository, while GitHub creates pull requests.

Pushing changes to GitHub as pull request¶

If you are translating a project that’s hosted on GitHub and don’t want to push translations to the repository, you can have them sent as a pull request instead.

You need to configure the hub command line tool and set GITHUB_USERNAME for this to work.

See also

GITHUB_USERNAME, Setting up hub for configuration instructions

Setting up hub¶

Pushing changes to GitHub as pull request requires a configured hub installation on your server. Follow the installation instructions at https://hub.github.com/ and perform an action with hub to finish the configuration, for example:

# DATA_DIR is set in Weblate settings.py, set it accordingy.
# Is is /app/data in Docker
HOME=${DATA_DIR}/home hub clone octocat/Spoon-Knife

The hub will ask you for your GitHub credentials, retrieve a token and store it into ~/.config/hub. This file has to be readable by user running Weblate.

Note

Use the username you configured hub with as GITHUB_USERNAME (WEBLATE_GITHUB_USERNAME for the Docker image).

Gerrit¶

New in version 2.2.

Adds a thin layer atop Git to allow pushing translation changes as Gerrit review requests, instead of pushing a directory to the repository. Currently uses the git-review tool to do the integration.

Please refer to the Gerrit documentation for setting up the repository with necessary configuration.

Mercurial¶

New in version 2.1.

Mercurial is another VCS you can use directly in Weblate.

Note

It should work with any Mercurial version, but there are sometimes incompatible changes to the command line interface which break Weblate.

See also

See Accessing repositories for information how to access different kind of repositories.

Subversion¶

New in version 2.8.

Thanks to git-svn, Weblate can work with subversion repositories. Git-svn is a Perl script that enables the usage of subversion with a git client, enabling users to have a full clone of the internal repository and commit locally.

Note

Weblate tries to detect Subversion repository layout automatically - it supports both direct URLs for branch or repositories with standard layout (branches/, tags/ and trunk/). See git-svn documentation for more information.

Changed in version 2.19: In older versions only repositories with standard layout were supported.

Subversion Credentials¶

Weblate expects you to have accepted the certificate upfront and inserted your credential, if needed. It will look into the DATA_DIR directory. To insert your credential and accept the certificate, you can run svn once with the $HOME environment variable set to the DATA_DIR:

HOME=${DATA_DIR}/home svn co https://svn.example.com/example

See also

DATA_DIR

Local files¶

New in version 3.8.

Weblate can operate without remote VCS as well. The initial translations are imported by ZIP upload. Later you can replace individual files by file upload or add translation strings directly in Weblate (currently available only for monolingual translations).

In the background Weblate creates Git repository for you and all changes are tracked in in. In case you decide later to use VCS to store the translations, it’s already within Weblate and you can base on that.

Weblate’s Web API¶

REST API¶

New in version 2.6: The API is available since Weblate 2.6.

The API is accessible on the /api/ URL and it is based on Django REST framework. You can use it directly or by Weblate Client.

Authentication and generic parameters¶

The public project API is available without authentication, though unauthenticated requests are heavily throttled (by default to 100 requests per day), so it is recommended to use authentication. The authentication uses a token, which you can get in your profile. Use it in the Authorization header:

ANY /¶

Generic request behaviour for the API, the headers, status codes and parameters here apply to all endpoints as well.

Query Parameters:
	format – Response format (overrides Accept). Possible values depends on REST framework setup, by default `json` and `api` are supported. The latter provides web browser interface for API.
Request Headers:
	Accept – the response content type depends on Accept header Authorization – optional token to authenticate
Response Headers:
	Content-Type – this depends on Accept header of request Allow – list of allowed HTTP methods on object
Response JSON Object:
	detail (string) – verbose description of failure (for HTTP status codes other than 200 OK) count (int) – total item count for object lists next (string) – next page URL for object lists previous (string) – previous page URL for object lists results (array) – results for object lists url (string) – URL to access this resource using API web_url (string) – URL to access this resource using web browser
Status Codes:	200 OK – when request was correctly handled 400 Bad Request – when form parameters are missing 403 Forbidden – when access is denied 429 Too Many Requests – when throttling is in place

Authentication examples¶

Example request:

GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Authorization: Token YOUR-TOKEN

Example response:

HTTP/1.0 200 OK
Date: Fri, 25 Mar 2016 09:46:12 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS

{
    "projects":"http://example.com/api/projects/",
    "components":"http://example.com/api/components/",
    "translations":"http://example.com/api/translations/",
    "languages":"http://example.com/api/languages/"
}

CURL example:

curl \
    -H "Authorization: Token TOKEN" \
    https://example.com/api/

Passing Parameters Examples¶

For the POST method the parameters can be specified either as form submission (application/x-www-form-urlencoded) or as JSON (application/json).

Form request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Token TOKEN

operation=pull

JSON request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Token TOKEN
Content-Length: 20

{"operation":"pull"}

CURL example:

curl \
    -d operation=pull \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

CURL JSON example:

curl \
    --data-binary '{"operation":"pull"}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

Rate limiting¶

The API requests are rate limited; the default configuration limits it to 100 requests per day for anonymous users and 1000 requests per day for authenticated users.

Rate limiting can be adjusted in the settings.py; see Throttling in Django REST framework documentation for more details how to configure it.

API Entry Point¶

GET /api/¶

The API root entry point.

Example request:

GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Authorization: Token YOUR-TOKEN

Example response:

HTTP/1.0 200 OK
Date: Fri, 25 Mar 2016 09:46:12 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS

{
    "projects":"http://example.com/api/projects/",
    "components":"http://example.com/api/components/",
    "translations":"http://example.com/api/translations/",
    "languages":"http://example.com/api/languages/"
}

Languages¶

GET /api/languages/¶: Returns a list of all languages.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Language object attributes are documented at GET /api/languages/(string:language)/.

GET /api/languages/(string: language)/¶

Returns information about a language.

Response JSON Object:
Parameters:	language (string) – Language code
	code (string) – Language code direction (string) – Text direction

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "code": "en",
    "direction": "ltr",
    "name": "English",
    "url": "http://example.com/api/languages/en/",
    "web_url": "http://example.com/languages/en/"
}

Projects¶

GET /api/projects/¶: Returns a list of all projects.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Project object attributes are documented at GET /api/projects/(string:project)/.

GET /api/projects/(string: project)/¶

Returns information about a project.

Parameters:

project (string) – Project URL slug

Response JSON Object:

name (string) – project name
slug (string) – project slug
source_language (object) – source language object; see GET /api/languages/(string:language)/
web (string) – project website
components_list_url (string) – URL to components list; see GET /api/projects/(string:project)/components/
repository_url (string) – URL to repository status; see GET /api/projects/(string:project)/repository/
changes_list_url (string) – URL to changes list; see GET /api/projects/(string:project)/changes/

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "name": "Hello",
    "slug": "hello",
    "source_language": {
        "code": "en",
        "direction": "ltr",
        "name": "English",
        "url": "http://example.com/api/languages/en/",
        "web_url": "http://example.com/languages/en/"
    },
    "url": "http://example.com/api/projects/hello/",
    "web": "https://weblate.org/",
    "web_url": "http://example.com/projects/hello/"
}

GET /api/projects/(string: project)/changes/¶

Returns a list of project changes.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	results (array) – array of component objects; see `GET /api/changes/(int:pk)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/projects/(string: project)/repository/¶

Returns information about VCS repository status. This endpoint contains only an overall summary for all repositories for the project. To get more detailed status use GET /api/components/(string:project)/(string:component)/repository/.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	needs_commit (boolean) – whether there are any pending changes to commit needs_merge (boolean) – whether there are any upstream changes to merge needs_push (boolean) – whether there are any local changes to push

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "needs_commit": true,
    "needs_merge": false,
    "needs_push": true
}

POST /api/projects/(string: project)/repository/¶

Performs given operation on the VCS repository.

Request JSON Object:
Parameters:	project (string) – Project URL slug
	operation (string) – Operation to perform: one of `push`, `pull`, `commit`, `reset`, `cleanup`
Response JSON Object:
	result (boolean) – result of the operation

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

CURL example:

curl \
    -d operation=pull \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

JSON request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Token TOKEN
Content-Length: 20

{"operation":"pull"}

JSON response example:

HTTP/1.0 200 OK
Date: Tue, 12 Apr 2016 09:32:50 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, POST, HEAD, OPTIONS

{"result":true}

GET /api/projects/(string: project)/components/¶

Returns a list of translation components in the given project.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	results (array) – array of component objects; see `GET /api/components/(string:project)/(string:component)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/projects/(string: project)/languages/¶

Returns paginated statistics for all languages within a project.

New in version 3.8.

Parameters:

project (string) – Project URL slug

Response JSON Object:

results (array) – array of translation statistics objects
language (string) – language name
code (string) – language code
total (int) – total number of strings
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
total_words (int) – total number of words
translated_words (int) – number of translated words
words_percent (float) – percentage of translated words

GET /api/projects/(string: project)/statistics/¶

Returns statistics for a project.

New in version 3.8.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	total (int) – total number of strings translated (int) – number of translated strings translated_percent (float) – percentage of translated strings total_words (int) – total number of words translated_words (int) – number of translated words words_percent (float) – percentage of translated words

Components¶

GET /api/components/¶: Returns a list of translation components.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Component object attributes are documented at GET /api/components/(string:project)/(string:component)/.

GET /api/components/(string: project)/(string: component)/¶

Returns information about translation component.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug

Response JSON Object:

branch (string) – VCS repository branch
file_format (string) – file format of translations
filemask (string) – mask of translation files in the repository
git_export (string) – URL of the exported VCS repository with translations
license (string) – license for translations
license_url (string) – URL of license for translations
name (string) – name of component
slug (string) – slug of component
project (object) – the translation project; see GET /api/projects/(string:project)/
repo (string) – VCS repository URL
template (string) – base file for monolingual translations
new_base (string) – base file for adding new translations
vcs (string) – version control system
repository_url (string) – URL to repository status; see GET /api/components/(string:project)/(string:component)/repository/
translations_url (string) – URL to translations list; see GET /api/components/(string:project)/(string:component)/translations/
lock_url (string) – URL to lock status; see GET /api/components/(string:project)/(string:component)/lock/
changes_list_url (string) – URL to changes list; see GET /api/components/(string:project)/(string:component)/changes/

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "branch": "master",
    "file_format": "po",
    "filemask": "po/*.po",
    "git_export": "",
    "license": "",
    "license_url": "",
    "name": "Weblate",
    "slug": "weblate",
    "project": {
        "name": "Hello",
        "slug": "hello",
        "source_language": {
            "code": "en",
            "direction": "ltr",
            "name": "English",
            "url": "http://example.com/api/languages/en/",
            "web_url": "http://example.com/languages/en/"
        },
        "url": "http://example.com/api/projects/hello/",
        "web": "https://weblate.org/",
        "web_url": "http://example.com/projects/hello/"
    },
    "repo": "file:///home/nijel/work/weblate-hello",
    "template": "",
    "new_base": "",
    "url": "http://example.com/api/components/hello/weblate/",
    "vcs": "git",
    "web_url": "http://example.com/projects/hello/weblate/"
}

GET /api/components/(string: project)/(string: component)/changes/¶

Returns a list of component changes.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	results (array) – array of component objects; see `GET /api/changes/(int:pk)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/lock/¶

Returns component lock status.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	locked (boolean) – whether component is locked for updates

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "locked": false
}

POST /api/components/(string: project)/(string: component)/lock/¶

Sets component lock status.

Response is same as GET /api/components/(string:project)/(string:component)/lock/.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	lock – Boolean whether to lock or not.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/repository/¶

Returns information about VCS repository status.

The response is same as for GET /api/projects/(string:project)/repository/.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug

Response JSON Object:

needs_commit (boolean) – whether there are any pending changes to commit
needs_merge (boolean) – whether there are any upstream changes to merge
needs_push (boolean) – whether there are any local changes to push
remote_commit (string) – Remote commit information
status (string) – VCS repository status as reported by VCS
merge_failure – Text describing merge failure or null if there is none

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/components/(string: project)/(string: component)/repository/¶

Performs the given operation on a VCS repository.

See POST /api/projects/(string:project)/repository/ for documentation.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	operation (string) – Operation to perform: one of `push`, `pull`, `commit`, `reset`, `cleanup`
Response JSON Object:
	result (boolean) – result of the operation

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/monolingual_base/¶

Downloads base file for monolingual translations.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/new_template/¶

Downloads template file for new translations.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/translations/¶

Returns a list of translation objects in the given component.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	results (array) – array of translation objects; see `GET /api/translations/(string:project)/(string:component)/(string:language)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/statistics/¶

Returns paginated statistics for all translations within component.

New in version 2.7.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	results (array) – array of translation statistics objects; see `GET /api/translations/(string:project)/(string:component)/(string:language)/statistics/`

Translations¶

GET /api/translations/¶: Returns a list of translations.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Translation object attributes are documented at GET /api/translations/(string:project)/(string:component)/(string:language)/.

GET /api/translations/(string: project)/(string: component)/(string: language)/¶

Returns information about a translation.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code

Response JSON Object:

component (object) – component object; see GET /api/components/(string:project)/(string:component)/
failing_checks (int) – number of strings failing check
failing_checks_percent (float) – percentage of strings failing check
failing_checks_words (int) – number of words with failing check
filename (string) – translation filename
fuzzy (int) – number of strings marked for review
fuzzy_percent (float) – percentage of strings marked for review
fuzzy_words (int) – number of words marked for review
have_comment (int) – number of strings with comment
have_suggestion (int) – number of strings with suggestion
is_template (boolean) – whether translation is monolingual base
language (object) – source language object; see GET /api/languages/(string:language)/
language_code (string) – language code used in the repository; this can be different from language code in the language object
last_author (string) – name of last author
last_change (timestamp) – last change timestamp
revision (string) – hash revision of the file
share_url (string) – URL for sharing leading to engage page
total (int) – total number of strings
total_words (int) – total number of words
translate_url (string) – URL for translating
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
translated_words (int) – number of translated words
repository_url (string) – URL to repository status; see GET /api/translations/(string:project)/(string:component)/(string:language)/repository/
file_url (string) – URL to file object; see GET /api/translations/(string:project)/(string:component)/(string:language)/file/
changes_list_url (string) – URL to changes list; see GET /api/translations/(string:project)/(string:component)/(string:language)/changes/
units_list_url (string) – URL to strings list; see GET /api/translations/(string:project)/(string:component)/(string:language)/units/

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "component": {
        "branch": "master",
        "file_format": "po",
        "filemask": "po/*.po",
        "git_export": "",
        "license": "",
        "license_url": "",
        "name": "Weblate",
        "new_base": "",
        "project": {
            "name": "Hello",
            "slug": "hello",
            "source_language": {
                "code": "en",
                "direction": "ltr",
                "name": "English",
                "url": "http://example.com/api/languages/en/",
                "web_url": "http://example.com/languages/en/"
            },
            "url": "http://example.com/api/projects/hello/",
            "web": "https://weblate.org/",
            "web_url": "http://example.com/projects/hello/"
        },
        "repo": "file:///home/nijel/work/weblate-hello",
        "slug": "weblate",
        "template": "",
        "url": "http://example.com/api/components/hello/weblate/",
        "vcs": "git",
        "web_url": "http://example.com/projects/hello/weblate/"
    },
    "failing_checks": 3,
    "failing_checks_percent": 75.0,
    "failing_checks_words": 11,
    "filename": "po/cs.po",
    "fuzzy": 0,
    "fuzzy_percent": 0.0,
    "fuzzy_words": 0,
    "have_comment": 0,
    "have_suggestion": 0,
    "is_template": false,
    "language": {
        "code": "cs",
        "direction": "ltr",
        "name": "Czech",
        "url": "http://example.com/api/languages/cs/",
        "web_url": "http://example.com/languages/cs/"
    },
    "language_code": "cs",
    "last_author": "Weblate Admin",
    "last_change": "2016-03-07T10:20:05.499",
    "revision": "7ddfafe6daaf57fc8654cc852ea6be212b015792",
    "share_url": "http://example.com/engage/hello/cs/",
    "total": 4,
    "total_words": 15,
    "translate_url": "http://example.com/translate/hello/weblate/cs/",
    "translated": 4,
    "translated_percent": 100.0,
    "translated_words": 15,
    "url": "http://example.com/api/translations/hello/weblate/cs/",
    "web_url": "http://example.com/projects/hello/weblate/cs/"
}

GET /api/translations/(string: project)/(string: component)/(string: language)/changes/¶

Returns a list of translation changes.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code
	results (array) – array of component objects; see `GET /api/changes/(int:pk)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/translations/(string: project)/(string: component)/(string: language)/units/¶

Returns a list of translation units.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code
	results (array) – array of component objects; see `GET /api/units/(int:pk)/`

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/translations/(string: project)/(string: component)/(string: language)/file/¶

Download current translation file as stored in VCS (without format parameter) or as converted to a standard format (currently supported: Gettext PO, MO, XLIFF and TBX).

Note

This API endpoint uses different logic for output than rest of API as it operates on whole file rather than on data. Set of accepted format parameter differs and without such parameter you get translation file as stored in VCS.

Query Parameters:
	format – File format to use; if not specified no format conversion happens; supported file formats: `po`, `mo`, `xliff`, `xliff11`, `tbx`
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/translations/(string: project)/(string: component)/(string: language)/file/¶

Upload new file with translations.

Form Parameters:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code
	boolean overwrite – Whether to overwrite existing translations (defaults to no) file file – Uploaded file string email – Author e-mail string author – Author name string method – Upload method (`translate`, `approve`, `suggest`, `fuzzy`, `replace`) string fuzzy – Fuzzy strings processing (empty, `process`, `approve`)

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

CURL example:

curl -X POST \
    -F file=@strings.xml \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/translations/hello/android/cs/file/

GET /api/translations/(string: project)/(string: component)/(string: language)/repository/¶

Returns information about VCS repository status.

The response is same as for GET /api/components/(string:project)/(string:component)/repository/.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/translations/(string: project)/(string: component)/(string: language)/repository/¶

Performs given operation on the VCS repository.

See POST /api/projects/(string:project)/repository/ for documentation.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code
	operation (string) – Operation to perform: one of `push`, `pull`, `commit`, `reset`, `cleanup`
Response JSON Object:
	result (boolean) – result of the operation

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/translations/(string: project)/(string: component)/(string: language)/statistics/¶

Returns detailed translation statistics.

New in version 2.7.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code

Response JSON Object:

code (string) – language code
failing (int) – number of failing checks
failing_percent (float) – percentage of failing checks
fuzzy (int) – number of strings needing review
fuzzy_percent (float) – percentage of strings needing review
total_words (int) – total number of words
translated_words (int) – number of translated words
last_author (string) – name of last author
last_change (timestamp) – date of last change
name (string) – language name
total (int) – total number of strings
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
url (string) – URL to access the translation (engagement URL)
url_translate (string) – URL to access the translation (real translation URL)

Units¶

New in version 2.10.

GET /api/units/¶: Returns list of translation units.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Unit object attributes are documented at GET /api/units/(int:pk)/.

GET /api/units/(int: pk)/¶

Returns information about translation unit.

Parameters:

pk (int) – Unit ID

Response JSON Object:

translation (string) – URL of a related translation object
source (string) – source string
previous_source (string) – previous source string used for fuzzy matching
target (string) – target string
id_hash (string) – unique identifier of the unit
content_hash (string) – unique identifier of the source string
location (string) – location of the unit in source code
context (string) – translation unit context
comment (string) – translation unit comment
flags (string) – translation unit flags
fuzzy (boolean) – whether unit is fuzzy or marked for review
translated (boolean) – whether unit is translated
position (int) – unit position in translation file
has_suggestion (boolean) – whether unit has suggestions
has_comment (boolean) – whether unit has comments
has_failing_check (boolean) – whether unit has failing checks
num_words (int) – number of source words
priority (int) – translation priority; 100 is default
id (int) – unit identifier
web_url (string) – URL where unit can be edited
souce_info (string) – Source string information link; see GET /api/sources/(int:pk)/

Changes¶

New in version 2.10.

GET /api/changes/¶: Returns a list of translation changes.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Change object attributes are documented at GET /api/changes/(int:pk)/.

GET /api/changes/(int: pk)/¶

Returns information about translation change.

Parameters:

pk (int) – Change ID

Response JSON Object:

unit (string) – URL of a related unit object
translation (string) – URL of a related translation object
component (string) – URL of a related component object
dictionary (string) – URL of a related dictionary object
user (string) – URL of a related user object
author (string) – URL of a related author object
timestamp (timestamp) – event timestamp
action (int) – numeric identification of action
action_name (string) – text description of action
target (string) – event changed text or detail
id (int) – change identifier

Sources¶

New in version 2.14.

GET /api/sources/¶: Returns a list of source string information.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Sources object attributes are documented at GET /api/sources/(int:pk)/.

GET /api/sources/(int: pk)/¶

Returns information about source information.

Parameters:

pk (int) – Source information ID

Response JSON Object:

id_hash (string) – unique identifier of the unit
component (string) – URL of a related component object
timestamp (timestamp) – timestamp when source string was first seen by Weblate
priority (int) – source string priority, 100 is default
check_flags (string) – source string flags
units (array) – links to units; see GET /api/units/(int:pk)/
screenshots (array) – links to assigned screenshots; see GET /api/screenshots/(int:pk)/

Screenshots¶

New in version 2.14.

GET /api/screenshots/¶: Returns a list of screenshot string information.

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Sources object attributes are documented at GET /api/screenshots/(int:pk)/.

GET /api/screenshots/(int: pk)/¶

Returns information about screenshot information.

Response JSON Object:
Parameters:	pk (int) – Screenshot ID
	name (string) – name of a screenshot component (string) – URL of a related component object file_url (string) – URL to download a file; see `GET /api/screenshots/(int:pk)/file/` sources (array) – link to associated source string information; see `GET /api/sources/(int:pk)/`

GET /api/screenshots/(int: pk)/file/¶

Download the screenshot image.

Parameters:	pk (int) – Screenshot ID

POST /api/screenshots/(int: pk)/file/¶

Replace screenshot image.

Form Parameters:
Parameters:	pk (int) – Screenshot ID
	file image – Uploaded file

See also

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

CURL example:

curl -X POST \
    -F image=@image.png \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/screenshots/1/file/

Notification hooks¶

Notification hooks allow external applications to notify Weblate that the VCS repository has been updated.

You can use repository endpoints for projects, components and translations to update individual repositories; see POST /api/projects/(string:project)/repository/ for documentation.

GET /hooks/update/(string: project)/(string: component)/¶: Deprecated since version 2.6: Please use POST /api/components/(string:project)/(string:component)/repository/ instead which works properly with authentication for ACL limited projects.

Triggers update of a component (pulling from VCS and scanning for translation changes).

GET /hooks/update/(string: project)/¶: Deprecated since version 2.6: Please use POST /api/projects/(string:project)/repository/ instead which works properly with authentication for ACL limited projects.

Triggers update of all components in a project (pulling from VCS and scanning for translation changes).

POST /hooks/github/¶

Special hook for handling GitHub notifications and automatically updating matching components.

Note

GitHub includes direct support for notifying Weblate: enable Weblate service hook in repository settings and set the URL to the URL of your Weblate installation.

See also

Automatically receiving changes from GitHub: For instruction on setting up GitHub integration
https://help.github.com/articles/creating-webhooks: Generic information about GitHub Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/gitlab/¶

Special hook for handling GitLab notifications and automatically updating matching components.

See also

Automatically receiving changes from GitLab: For instruction on setting up GitLab integration
https://docs.gitlab.com/ce/user/project/integrations/webhooks.html: Generic information about GitLab Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/bitbucket/¶

Special hook for handling Bitbucket notifications and automatically updating matching components.

See also

Automatically receiving changes from Bitbucket: For instruction on setting up Bitbucket integration
https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html: Generic information about Bitbucket Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/pagure/¶

Special hook for handling Pagure notifications and automatically updating matching components.

See also

Automatically receiving changes from Pagure: For instruction on setting up Pagure integration
https://docs.pagure.org/pagure/usage/using_webhooks.html: Generic information about Pagure Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/azure/¶

Special hook for handling Azure Repos notifications and automatically updating matching components.

See also

Automatically receiving changes from Azure Repos: For instruction on setting up Azure integration
https://docs.microsoft.com/azure/devops/service-hooks/services/webhooks: Generic information about Azure Repos Web Hooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

Exports¶

Weblate provides various exports to allow you to further process the data.

GET /exports/stats/(string: project)/(string: component)/¶

Query Parameters:
	format (string) – Output format: either `json` or `csv`

Deprecated since version 2.6: Please use GET /api/components/(string:project)/(string:component)/statistics/ and GET /api/translations/(string:project)/(string:component)/(string:language)/statistics/ instead; it allows access to ACL controlled projects as well.

Retrieves statistics for given component in given format.

Example request:

GET /exports/stats/weblate/master/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "code": "cs",
        "failing": 0,
        "failing_percent": 0.0,
        "fuzzy": 0,
        "fuzzy_percent": 0.0,
        "last_author": "Michal \u010ciha\u0159",
        "last_change": "2012-03-28T15:07:38+00:00",
        "name": "Czech",
        "total": 436,
        "total_words": 15271,
        "translated": 436,
        "translated_percent": 100.0,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/cs/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/cs/"
    },
    {
        "code": "nl",
        "failing": 21,
        "failing_percent": 4.8,
        "fuzzy": 11,
        "fuzzy_percent": 2.5,
        "last_author": null,
        "last_change": null,
        "name": "Dutch",
        "total": 436,
        "total_words": 15271,
        "translated": 319,
        "translated_percent": 73.2,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/nl/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/nl/"
    },
    {
        "code": "el",
        "failing": 11,
        "failing_percent": 2.5,
        "fuzzy": 21,
        "fuzzy_percent": 4.8,
        "last_author": null,
        "last_change": null,
        "name": "Greek",
        "total": 436,
        "total_words": 15271,
        "translated": 312,
        "translated_percent": 71.6,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/el/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/el/"
    },
]

RSS feeds¶

Changes in translations are exported in RSS feeds.

GET /exports/rss/(string: project)/(string: component)/(string: language)/¶: Retrieves RSS feed with recent changes for a translation.

GET /exports/rss/(string: project)/(string: component)/¶: Retrieves RSS feed with recent changes for a component.

GET /exports/rss/(string: project)/¶: Retrieves RSS feed with recent changes for a project.

GET /exports/rss/language/(string: language)/¶: Retrieves RSS feed with recent changes for a language.

GET /exports/rss/¶: Retrieves RSS feed with recent changes for Weblate instance.

See also

RSS on wikipedia

Weblate Client¶

New in version 2.7: The wlc utility is fully supported since Weblate 2.7. If you are using an older version some incompatibilities with the API might occur.

Installation¶

The Weblate Client is shipped separately and includes the Python module. You need to install wlc:, wlc to use these.

pip3 install wlc

Synopsis¶

wlc [parameter] <command> [options]

Commands actually indicate which operation should be performed.

Description¶

Weblate Client is Python library and command line utility to manage Weblate remotely using Weblate’s Web API. The command line utility can be invoked as wlc and is built on wlc.

Global options¶

The program accepts the following global options, which must be entered before subcommand.

--format {csv,json,text,html}¶: Specify output format.

--url URL¶: Specify API URL. Overrides value from configuration file, see Files. The URL should end with /api/, for example https://hosted.weblate.org/api/.

--key KEY¶: Specify API user key to use. Overrides value from configuration file, see Files. You can figure out your key in your profile in Weblate.

--config PATH¶: Override path to configuration file, see Files.

--config-section SECTION¶: Override section to use in configuration file, see Files.

Subcommands¶

Currently the following subcommands are available:

version¶: Prints current version.

list-languages¶: List used languages in Weblate.

list-projects¶: List projects in Weblate.

list-components¶: List components in Weblate.

list-translations¶: List translations in Weblate.

show¶: Shows Weblate object (translation, component or project).

ls¶: Lists Weblate object (translation, component or project).

commit¶: Commits changes in Weblate object (translation, component or project).

pull¶: Pulls remote repository changes into Weblate object (translation, component or project).

push¶: Pushes changes in Weblate object into remote repository (translation, component or project).

reset¶: New in version 0.7: Supported since wlc 0.7.

Resets changes in Weblate object to match remote repository (translation, component or project).

cleanup¶: New in version 0.9: Supported since wlc 0.9.

Removes any untracked changes in Weblate object to match remote repository (translation, component or project).

repo¶: Displays repository status for given Weblate object (translation, component or project).

statistics¶: Displays detailed statistics for given Weblate object (translation, component or project).

lock-status¶: New in version 0.5: Supported since wlc 0.5.

Displays lock status.

lock¶: New in version 0.5: Supported since wlc 0.5.

Locks component from translating in Weblate.

unlock¶: New in version 0.5: Supported since wlc 0.5.

Unlocks component from translating in Weblate.

changes¶: New in version 0.7: Supported since wlc 0.7 and Weblate 2.10.

Displays changes for given object.

download¶

New in version 0.7: Supported since wlc 0.7.

Downloads translation file.

--convert¶: Convert file format, if not specified not conversion happens on server and file is downloaded as is in the repository.

--output¶: File where to store output, if not specified file is printed to stdout.

upload¶

New in version 0.9: Supported since wlc 0.9.

Uploads translation file.

--overwrite¶: Overwrite existing translations on upload.

--input¶: File where to read content, if not specified file is read from stdin.

Files¶

.weblate: Per project configuration file
~/.config/weblate: User configuration file
/etc/xdg/weblate: Global configuration file

The program follows XDG specification, so you can adjust placement of config files by environment variables XDG_CONFIG_HOME or XDG_CONFIG_DIRS.

Following settings can be configured in the [weblate] section (you can customize this by --config-section):

key: API KEY to access Weblate.

url: API server URL, defaults to http://127.0.0.1:8000/api/.

translation: Path of default translation, component or project.

The configuration file is INI file, for example:

[weblate]
url = https://hosted.weblate.org/api/
key = APIKEY
translation = weblate/master

Additionally API keys can be stored in the [keys] section:

[keys]
https://hosted.weblate.org/api/ = APIKEY

This allows you to store keys in your personal settings, while having .weblate configuration in the VCS repository so that wlc knows to which server it should talk.

Examples¶

Print current program version:

$ wlc version
version: 0.1

List all projects:

$ wlc list-projects
name: Hello
slug: hello
source_language: en
url: http://example.com/api/projects/hello/
web: https://weblate.org/
web_url: http://example.com/projects/hello/

You can also let wlc know current project and it will then operate on it:

$ cat .weblate
[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/master

$ wlc show
branch: master
file_format: po
filemask: weblate/locale/*/LC_MESSAGES/django.po
git_export: https://hosted.weblate.org/git/weblate/master/
license: GPL-3.0+
license_url: https://spdx.org/licenses/GPL-3.0+
name: master
new_base: weblate/locale/django.pot
project: weblate
repo: git://github.com/WeblateOrg/weblate.git
slug: master
template:
url: https://hosted.weblate.org/api/components/weblate/master/
vcs: git
web_url: https://hosted.weblate.org/projects/weblate/master/

With such setup it is easy to commit pending changes in current project:

$ wlc commit

Weblate’s Python API¶

Installation¶

The Python API is shipped separately, you need to install Weblate Client:, wlc, to have it.

pip install wlc

`wlc`¶

`WeblateException`¶

exception wlc.WeblateException¶: Base class for all exceptions.

`Weblate`¶

class wlc.Weblate(key='', url=None, config=None)¶

Parameters:	key (str) – User key url (str) – API server URL, if not specified default is used config (wlc.config.WeblateConfig) – Configuration object, overrides any other parameters.

Access class to the API, define API key and optionally API URL.

get(path)¶

Parameters:	path (str) – Request path
Return type:	object

Performs single API GET call.

post(path, **kwargs)¶

Parameters:	path (str) – Request path
Return type:	object

Performs single API GET call.

`wlc.config`¶

`WeblateConfig`¶

class wlc.config.WeblateConfig(section='wlc')¶

Parameters:	section (str) – Configuration section to use

Configuration file parser following XDG specification.

load(path=None)¶

Parameters:	path (str) – Path from which to load configuration.

Loads configuration from a file, if none is specified it loads from wlc configuration file placed in XDG configuration path (~/.config/wlc and /etc/xdg/wlc).

`wlc.main`¶

wlc.main.main(settings=None, stdout=None, args=None)¶

Parameters:	settings (list) – settings to override as list of tuples stdout (object) – stdout file object for printing output, uses `sys.stdout` as default args (list) – command line arguments to process, uses `sys.args` as default

Main entry point for command line interface.

@wlc.main.register_command(command)¶: Decorator to register Command class in main parser used by main().

`Command`¶

class wlc.main.Command(args, config, stdout=None)¶: Main class for invoking commands.

Installation instructions¶

Installing using Docker¶

Hardware requirements¶

Weblate should run on all contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and webserver):

2 GB of RAM
2 CPU cores
1 GB of storage space

The more memory the better - it is used for caching on all levels (filesystem, database and Weblate).

Many concurrent users increases the amount of needed CPU cores. For hundreds of translation components at least 4 GB of RAM is recommended.

Note

Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.

Installation¶

Clone weblate-docker repo:

git clone https://github.com/WeblateOrg/docker-compose.git weblate-docker
cd weblate-docker

Start Weblate containers:
```
docker-compose up
```

See also

See Running Weblate with Docker for more detailed instructions and customization options.

Installing on Debian and Ubuntu¶

Hardware requirements¶

Weblate should run on all contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and webserver):

2 GB of RAM
2 CPU cores
1 GB of storage space

The more memory the better - it is used for caching on all levels (filesystem, database and Weblate).

Many concurrent users increases the amount of needed CPU cores. For hundreds of translation components at least 4 GB of RAM is recommended.

Note

Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.

Installation¶

System requirements¶

Install the dependencies needed to build the Python modules (see Software requirements):

apt install \
   libxml2-dev libxslt-dev libfreetype6-dev libjpeg-dev libz-dev libyaml-dev \
   libcairo-dev gir1.2-pango-1.0 libgirepository1.0-dev \
   build-essential python3-gdbm python3-dev python3-pip python3-virtualenv virtualenv

Install wanted optional dependencies depending on features you intend to use (see Optional dependecies):

apt install tesseract-ocr libtesseract-dev libleptonica-dev

Optionally install software for running production server, see Running server, Database setup for Weblate, Background tasks using Celery. Depending on size of your installation you might want to run these components on dedicated servers.

The local installation instructions:

# Web server option 1: NGINX and uWSGI
apt install nginx uwsgi uwsgi-plugin-python3

# Web server option 2: Apache with ``mod_wsgi``
apt install apache2 libapache2-mod-wsgi

# Caching backend: Redis
apt install redis-server

# Database server: PostgreSQL
apt install postgresql

# SMTP server
apt install exim4

Python modules¶

Hint

We’re using virtualenv to install Weblate in a separate environment from your system. If you are not familiar with it, check virtualenv User Guide.

Create the virtualenv for Weblate:

virtualenv --python=python3 ~/weblate-env

Activate the virtualenv for Weblate:
```
. ~/weblate-env/bin/activate
```
Install Weblate including all dependencies:
```
pip install Weblate
```
Install database driver:
```
pip install psycopg2-binary
```
Install wanted optional dependencies depending on features you intend to use (some might require additional system libraries, check Optional dependecies):
```
pip install ruamel.yaml aeidon boto3 zeep chardet tesserocr
```

Configuring Weblate¶

Copy the file ~/weblate-env/lib/python3.7/site-packages/weblate/settings_example.py to ~/weblate-env/lib/python3.7/site-packages/weblate/settings.py
Adjust the values in the new settings.py file to your liking. You can stick with shipped example for testing purposes, but you will want changes for production setup, see Adjusting configuration.
Create the database and its structure for Weblate (the example settings use SQLite, check Database setup for Weblate for pruduction ready setup):
```
weblate migrate
```
Create the administrator user account and copy the password it outputs to the clipboard, and also save it for later use:
```
weblate createadmin
```
Collect static files for web server (see Running server):
```
weblate collectstatic
```
Start Celery workers. This is not necessary for development purposes, but strongly recommended otherwise. See Background tasks using Celery for more info:
```
~/weblate-env/lib/python3.7/site-packages/weblate/examples/celery start
```
Start the development server (see Running server for production setup):
```
weblate runserver
```

After installation¶

Congratulations, your Weblate server is now running and you can start using it.

You can now access Weblate on http://localhost:8000/.
Login with admin credentials obtained during installation or register with new users.
You can now run Weblate commands using weblate command when Weblate virtualenv is active, see Management commands.
You can stop the test server with Ctrl+C.

Adding translation¶

Open the admin interface (http://localhost:8000/create/project/) and create the project you want to translate. See Project configuration for more details.

All you need to specify here is the project name and its website.
Create a component which is the real object for translation - it points to the VCS repository, and selects which files to translate. See Component configuration for more details.

The important fields here are: Component name, VCS repository address and mask for finding translatable files. Weblate supports a wide range of formats including gettext PO files, Android resource strings, iOS string properties, Java properties or Qt Linguist files, see Supported file formats for more details.
Once the above is completed (it can be lengthy process depending on the size of your VCS repository, and number of messages to translate), you can start translating.

Installing on SUSE and openSUSE¶

Hardware requirements¶

Weblate should run on all contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and webserver):

2 GB of RAM
2 CPU cores
1 GB of storage space

The more memory the better - it is used for caching on all levels (filesystem, database and Weblate).

Many concurrent users increases the amount of needed CPU cores. For hundreds of translation components at least 4 GB of RAM is recommended.

Note

Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.

Installation¶

System requirements¶

Install the dependencies needed to build the Python modules (see Software requirements):

zypper install \
   libxslt-devel libxml2-devel freetype-devel libjpeg-devel zlib-devel libyaml-devel \
   cairo-devel typelib-1_0-Pango-1_0 gobject-introspection-devel \
   python3-pip python3-virtualenv python3-devel

Install wanted optional dependencies depending on features you intend to use (see Optional dependecies):

zypper install tesseract-ocr tesseract-devel leptonica-devel

The local installation instructions:

# Web server option 1: NGINX and uWSGI
zypper install nginx uwsgi uwsgi-plugin-python3

# Web server option 2: Apache with ``mod_wsgi``
zypper install apache2 apache2-mod_wsgi

# Caching backend: Redis
zypper install redis-server

# Database server: PostgreSQL
zypper install postgresql

# SMTP server
zypper install postfix

Python modules¶

Hint

We’re using virtualenv to install Weblate in a separate environment from your system. If you are not familiar with it, check virtualenv User Guide.

Create the virtualenv for Weblate:

virtualenv --python=python3 ~/weblate-env

Activate the virtualenv for Weblate:
```
. ~/weblate-env/bin/activate
```
Install Weblate including all dependencies:
```
pip install Weblate
```
Install database driver:
```
pip install psycopg2-binary
```
Install wanted optional dependencies depending on features you intend to use (some might require additional system libraries, check Optional dependecies):
```
pip install ruamel.yaml aeidon boto3 zeep chardet tesserocr
```

Configuring Weblate¶

Copy the file ~/weblate-env/lib/python3.7/site-packages/weblate/settings_example.py to ~/weblate-env/lib/python3.7/site-packages/weblate/settings.py
Adjust the values in the new settings.py file to your liking. You can stick with shipped example for testing purposes, but you will want changes for production setup, see Adjusting configuration.
Create the database and its structure for Weblate (the example settings use SQLite, check Database setup for Weblate for pruduction ready setup):
```
weblate migrate
```
Create the administrator user account and copy the password it outputs to the clipboard, and also save it for later use:
```
weblate createadmin
```
Collect static files for web server (see Running server):
```
weblate collectstatic
```
Start Celery workers. This is not necessary for development purposes, but strongly recommended otherwise. See Background tasks using Celery for more info:
```
~/weblate-env/lib/python3.7/site-packages/weblate/examples/celery start
```
Start the development server (see Running server for production setup):
```
weblate runserver
```

After installation¶

Congratulations, your Weblate server is now running and you can start using it.

You can now access Weblate on http://localhost:8000/.
Login with admin credentials obtained during installation or register with new users.
You can now run Weblate commands using weblate command when Weblate virtualenv is active, see Management commands.
You can stop the test server with Ctrl+C.

Adding translation¶

Open the admin interface (http://localhost:8000/create/project/) and create the project you want to translate. See Project configuration for more details.

All you need to specify here is the project name and its website.
Create a component which is the real object for translation - it points to the VCS repository, and selects which files to translate. See Component configuration for more details.

The important fields here are: Component name, VCS repository address and mask for finding translatable files. Weblate supports a wide range of formats including gettext PO files, Android resource strings, iOS string properties, Java properties or Qt Linguist files, see Supported file formats for more details.
Once the above is completed (it can be lengthy process depending on the size of your VCS repository, and number of messages to translate), you can start translating.

Installing on RedHat, Fedora and CentOS¶

Hardware requirements¶

Weblate should run on all contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and webserver):

2 GB of RAM
2 CPU cores
1 GB of storage space

The more memory the better - it is used for caching on all levels (filesystem, database and Weblate).

Many concurrent users increases the amount of needed CPU cores. For hundreds of translation components at least 4 GB of RAM is recommended.

Note

Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.

Installation¶

System requirements¶

Install the dependencies needed to build the Python modules (see Software requirements):

dnf install \
   libxslt-devel libxml2-devel freetype-devel libjpeg-devel zlib-devel libyaml-devel \
   cairo-devel typelib-1_0-Pango-1_0 gobject-introspection-devel \
   python3-pip python3-virtualenv python3-devel

Install wanted optional dependencies depending on features you intend to use (see Optional dependecies):

dnf install tesseract-ocr tesseract-devel leptonica-devel

The local installation instructions:

# Web server option 1: NGINX and uWSGI
dnf install nginx uwsgi uwsgi-plugin-python3

# Web server option 2: Apache with ``mod_wsgi``
dnf install apache2 apache2-mod_wsgi

# Caching backend: Redis
dnf install redis-server

# Database server: PostgreSQL
dnf install postgresql

# SMTP server
dnf install postfix

Python modules¶

Hint

We’re using virtualenv to install Weblate in a separate environment from your system. If you are not familiar with it, check virtualenv User Guide.

Create the virtualenv for Weblate:

virtualenv --python=python3 ~/weblate-env

Activate the virtualenv for Weblate:
```
. ~/weblate-env/bin/activate
```
Install Weblate including all dependencies:
```
pip install Weblate
```
Install database driver:
```
pip install psycopg2-binary
```
Install wanted optional dependencies depending on features you intend to use (some might require additional system libraries, check Optional dependecies):
```
pip install ruamel.yaml aeidon boto3 zeep chardet tesserocr
```

Configuring Weblate¶

Copy the file ~/weblate-env/lib/python3.7/site-packages/weblate/settings_example.py to ~/weblate-env/lib/python3.7/site-packages/weblate/settings.py
Adjust the values in the new settings.py file to your liking. You can stick with shipped example for testing purposes, but you will want changes for production setup, see Adjusting configuration.
Create the database and its structure for Weblate (the example settings use SQLite, check Database setup for Weblate for pruduction ready setup):
```
weblate migrate
```
Create the administrator user account and copy the password it outputs to the clipboard, and also save it for later use:
```
weblate createadmin
```
Collect static files for web server (see Running server):
```
weblate collectstatic
```
Start Celery workers. This is not necessary for development purposes, but strongly recommended otherwise. See Background tasks using Celery for more info:
```
~/weblate-env/lib/python3.7/site-packages/weblate/examples/celery start
```
Start the development server (see Running server for production setup):
```
weblate runserver
```

After installation¶

Congratulations, your Weblate server is now running and you can start using it.

You can now access Weblate on http://localhost:8000/.
Login with admin credentials obtained during installation or register with new users.
You can now run Weblate commands using weblate command when Weblate virtualenv is active, see Management commands.
You can stop the test server with Ctrl+C.

Adding translation¶

Open the admin interface (http://localhost:8000/create/project/) and create the project you want to translate. See Project configuration for more details.

All you need to specify here is the project name and its website.
Create a component which is the real object for translation - it points to the VCS repository, and selects which files to translate. See Component configuration for more details.

The important fields here are: Component name, VCS repository address and mask for finding translatable files. Weblate supports a wide range of formats including gettext PO files, Android resource strings, iOS string properties, Java properties or Qt Linguist files, see Supported file formats for more details.
Once the above is completed (it can be lengthy process depending on the size of your VCS repository, and number of messages to translate), you can start translating.

Installing from sources¶

Please follow the installatin instructions for your system first:
Grab the latest Weblate sources using Git (or download a tarball and unpack that):
```
git clone https://github.com/WeblateOrg/weblate.git weblate-src
```
Alternatively you can use released archives. You can download them from our website <https://weblate.org/>. Those downloads are cryptographically signed, please see Verifying release signatures.

Install current Weblate code into the virtualenv:

. ~/weblate-env/bin/activate
pip install -e weblate-src

Copy weblate/settings_example.py to weblate/settings.py.
Adjust the values in the new settings.py file to your liking. You can stick with shipped example for testing purposes, but you will want changes for production setup, see Adjusting configuration.
Create the database used by Weblate, see Database setup for Weblate.
Build Django tables, static files and initial data (see Filling up the database and Serving static files):
```
./manage.py migrate
./manage.py collectstatic
./scripts/generate-locales
```
Note

This step should be repeated whenever you update the repository.

Installing on OpenShift 2¶

You can install Weblate on OpenShift PaaS directly from its Git repository using the OpenShift Client Tools:
```
rhc -aweblate app create -t python-2.7 --from-code https://github.com/WeblateOrg/weblate.git --no-git
```
After installation everything should be preconfigured, and you can immediately start adding a translation project as described below.

See also

For more info, including how to retrieve the generated admin password, see Running Weblate on OpenShift 2.

Depending on your setup and experience, choose appropriate installation method:

Installing using Docker, recommended for production setup.
Virtualenv installation, recommended for production setup:
Installing from sources, recommended for development.
Installing on OpenShift 2.

Configuration instructions¶

Installing Weblate¶

Choose an installation method that best fits your environment in our Installation instructions.

Software requirements¶

Other services¶

Weblate is using other services for it’s operation. You will need at least following services running:

PostgreSQL database server, see Database setup for Weblate.
Redis server for cache and tasks queue, see Background tasks using Celery.
SMTP server for outgoing e-mail, see Configuring outgoing e-mail.

Python dependencies¶

Weblate is written in Python and supports Python 2.7, 3.4 or newer. You can install dependencies using pip or from your distribution packages, full list of them is available in requirements.txt.

Most notable dependencies:

Django: https://www.djangoproject.com/
Celery: http://www.celeryproject.org/
Translate Toolkit: https://toolkit.translatehouse.org/
translation-finder: https://github.com/WeblateOrg/translation-finder
Python Social Auth: https://python-social-auth.readthedocs.io/
Whoosh: https://bitbucket.org/mchaput/whoosh/wiki/Home
Django REST Framework: https://www.django-rest-framework.org/

Optional dependecies¶

Following modules are necessary for some of Weblate features. You can find all of them in requirements-optional.txt.

Mercurial (optional for Mercurial repositories support): https://www.mercurial-scm.org/
phply (optional for PHP support): https://github.com/viraptor/phply
tesserocr (optional for screenshots OCR): https://github.com/sirfz/tesserocr
akismet (optional for suggestion spam protection): https://github.com/ubernostrum/akismet
ruamel.yaml (optional for YAML files): https://pypi.org/project/ruamel.yaml/
backports.csv (needed on Python 2.7): https://pypi.org/project/backports.csv/
Zeep (optional for Microsoft Terminology Service): https://python-zeep.readthedocs.io/
aeidon (optional for Subtitle files): https://pypi.org/project/aeidon/

Database backend dependencies¶

Any database supported in Django will work, see Database setup for Weblate and backends documentation for more details.

Other system requirements¶

The following dependencies have to be installed on the system:

Git: https://git-scm.com/
Pango, Cairo and related header files and gir introspection data: https://cairographics.org/, https://www.pango.org/, see Pango and Cairo
hub (optional for sending pull requests to GitHub): https://hub.github.com/
git-review (optional for Gerrit support): https://pypi.org/project/git-review/
git-svn (optional for Subversion support): https://git-scm.com/docs/git-svn
tesseract and it’s data (optional for screenshots OCR): https://github.com/tesseract-ocr/tesseract

Compile time dependencies¶

To compile some of the Python dependencies you might need to install their dependencies. This depends on how you install them, so please consult individual packages for documentation. You won’t need those if using prebuilt Wheels while installing using pip or when you use distribution packages.

Pango and Cairo¶

Changed in version 3.7.

Weblate uses Pango and Cairo for rendering bitmap widgets (see Promoting the translation) and rendering checks (see Managing fonts). To properly install Python bindings for those you need to install system libraries first - you need both Cairo and Pango, which in turn need Glib. All those should be installed with development files and GObject introspection data.

Verifying release signatures¶

Weblate release are cryptographically signed by the releasing developer. Currently this is Michal Čihař. Fingerprint of his PGP key is:

63CB 1DF1 EF12 CF2A C0EE 5A32 9C27 B313 42B7 511D

and you can get more identification information from <https://keybase.io/nijel>.

You should verify that the signature matches the archive you have downloaded. This way you can be sure that you are using the same code that was released. You should also verify the date of the signature to make sure that you downloaded the latest version.

Each archive is accompanied with .asc files which contains the PGP signature for it. Once you have both of them in the same folder, you can verify the signature:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Can't check signature: public key not found

As you can see gpg complains that it does not know the public key. At this point you should do one of the following steps:

Use wkd to download the key:

$ gpg --auto-key-locate wkd --locate-keys michal@cihar.com
pub   rsa4096 2009-06-17 [SC]
      63CB1DF1EF12CF2AC0EE5A329C27B31342B7511D
uid           [ultimate] Michal Čihař <michal@cihar.com>
uid           [ultimate] Michal Čihař <nijel@debian.org>
uid           [ultimate] [jpeg image of size 8848]
uid           [ultimate] Michal Čihař (Braiins) <michal.cihar@braiins.cz>
sub   rsa4096 2009-06-17 [E]
sub   rsa4096 2015-09-09 [S]

Download the keyring from Michal’s server, then import it with:

$ gpg --import wmxth3chu9jfxdxywj1skpmhsj311mzm

Download and import the key from one of the key servers:

$ gpg --keyserver hkp://pgp.mit.edu --recv-keys 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: key 9C27B31342B7511D: "Michal Čihař <michal@cihar.com>" imported
gpg: Total number processed: 1
gpg:              unchanged: 1

This will improve the situation a bit - at this point you can verify that the signature from the given key is correct but you still can not trust the name used in the key:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 63CB 1DF1 EF12 CF2A C0EE  5A32 9C27 B313 42B7 511D

The problem here is that anybody could issue the key with this name. You need to ensure that the key is actually owned by the mentioned person. The GNU Privacy Handbook covers this topic in the chapter Validating other keys on your public keyring. The most reliable method is to meet the developer in person and exchange key fingerprints, however you can also rely on the web of trust. This way you can trust the key transitively though signatures of others, who have met the developer in person.

Once the key is trusted, the warning will not occur:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]

Should the signature be invalid (the archive has been changed), you would get a clear error regardless of the fact that the key is trusted or not:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: BAD signature from "Michal Čihař <michal@cihar.com>" [ultimate]

Filesystem permissions¶

The Weblate process needs to be able to read and write to the directory where it keeps data - DATA_DIR.

The default configuration places them in the same tree as the Weblate sources, however you might prefer to move these to a better location such as: /var/lib/weblate.

Weblate tries to create these directories automatically, but it will fail when it does not have permissions to do so.

You should also take care when running Management commands, as they should be ran under the same user as Weblate itself is running, otherwise permissions on some files might be wrong.

See also

Serving static files

Database setup for Weblate¶

It is recommended to run Weblate with PostgreSQL database server. Using a SQLite backend is really only suitable for testing purposes.

PostgreSQL¶

PostgreSQL is usually the best choice for Django based sites. It’s the reference database used for implementing Django database layer.

See also

PostgreSQL notes

Creating a database in PostgreSQL¶

It is usually a good idea to run Weblate in a separate database, and separate user account:

# If PostgreSQL was not installed before, set the master password
sudo -u postgres psql postgres -c "\password postgres"

# Create a database user called "weblate"
sudo -u postgres createuser -D -P weblate

# Create the database "weblate" owned by "weblate"
sudo -u postgres createdb -O weblate weblate

Configuring Weblate to use PostgreSQL¶

The settings.py snippet for PostgreSQL:

DATABASES = {
    'default': {
        # Database engine
        'ENGINE': 'django.db.backends.postgresql',
        # Database name
        'NAME': 'weblate',
        # Database user
        'USER': 'weblate',
        # Database password
        'PASSWORD': 'password',
        # Set to empty string for localhost
        'HOST': 'database.example.com',
        # Set to empty string for default
        'PORT': '',
    }
}

MySQL or MariaDB¶

MySQL or MariaDB are quite good choices for running Weblate. However when using MySQL you might hit some problems caused by it.

Warning

It’s likely that MySQL/MariaDB support will be dropped in future Weblate releases, so it’s not recommended for new installations.

See also

MySQL notes

Unicode issues in MySQL¶

MySQL by default uses something called utf8, which can not store all Unicode characters, only those who fit into three bytes in utf-8 encoding. In case you’re using emojis or some other higher Unicode symbols you might hit errors when saving such data. Depending on the MySQL and Python bindings version, the produced error might look like this:

OperationalError: (1366, “Incorrect string value: ‘\xF0\xA8\xAB\xA1’ for column ‘target’ at row 1”)
UnicodeEncodeError: ‘ascii’ codec can’t encode characters in position 0-3: ordinal not in range(128)

To solve this, you need to change your database to use utf8mb4 (which is again a subset of Unicode, but this time one which can be stored in four bytes in utf-8 encoding, thus covering all chars currently defined in Unicode).

This can be achieved during creation of the database by selecting this character set (see Creating a database in MySQL) and specifying that character set in the connection settings (see Configuring Weblate to use MySQL).

In case you have an existing database, you can change it to utf8mb4 by, but this won’t change collation of existing fields:

ALTER DATABASE weblate CHARACTER SET utf8mb4;

Using this charset might however lead to problems with the default MySQL server settings, as each character now takes 4 bytes to store, and MySQL has an upper limit of 767 bytes for an index. In case this happens you will get one of the following error messages:

1071: Specified key was too long; max key length is 767 bytes
1709: Index column size too large. The maximum column size is 767 bytes.

There are two ways to work around this limitation. You can configure MySQL to not have this limit, see Using Innodb_large_prefix to Avoid ERROR 1071. Alternatively you can also adjust several settings for social-auth in your settings.py (see Configuration):

# Limit some social-auth fields to 191 chars to fit
# them in 767 bytes

SOCIAL_AUTH_UID_LENGTH = 191
SOCIAL_AUTH_NONCE_SERVER_URL_LENGTH = 191
SOCIAL_AUTH_ASSOCIATION_SERVER_URL_LENGTH = 191
SOCIAL_AUTH_ASSOCIATION_HANDLE_LENGTH = 191
SOCIAL_AUTH_EMAIL_LENGTH = 191

Transaction locking¶

MySQL by default uses a different transaction locking scheme than other databases, and in case you see errors like Deadlock found when trying to get lock; try restarting transaction it might be good idea to enable STRICT_TRANS_TABLES mode in MySQL. This can be done in the server configuration file (usually /etc/mysql/my.cnf on Linux):

[mysqld]
sql-mode=STRICT_TRANS_TABLES

See also

Setting sql_mode

Creating a database in MySQL¶

Create weblate user to access the weblate database:

# Grant all privileges to the user ``weblate``
GRANT ALL PRIVILEGES ON weblate.* TO 'weblate'@'localhost'  IDENTIFIED BY 'password';

# Create a database on MySQL >= 5.7.7
CREATE DATABASE weblate CHARACTER SET utf8mb4;

# Use utf8 for older versions
# CREATE DATABASE weblate CHARACTER SET utf8;

Configuring Weblate to use MySQL¶

The settings.py snippet for MySQL:

DATABASES = {
    'default': {
        # Database engine
        'ENGINE': 'django.db.backends.mysql',
        # Database name
        'NAME': 'weblate',
        # Database user
        'USER': 'weblate',
        # Database password
        'PASSWORD': 'password',
        # Set to empty string for localhost
        'HOST': 'database.example.com',
        # Set to empty string for default
        'PORT': '',
        # Additional database options
        'OPTIONS': {
            # In case of using an older MySQL server, which has MyISAM as a default storage
            # 'init_command': 'SET storage_engine=INNODB',
            # Uncomment for MySQL older than 5.7:
            # 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
            # If your server supports it, see the Unicode issues above
           'charset': 'utf8mb4',
        }

    }
}

Other configurations¶

Configuring outgoing e-mail¶

Weblate sends out e-mails on various occasions - for account activation and on various notifications configured by users. For this it needs access to a SMTP server.

The mail server setup is configured using these settings: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_HOST_USER and EMAIL_PORT. Their names are quite self-explanatory, but you can find more info in the Django documentation.

Note

You can verify whether outgoing e-mail is working correctly by using the sendtestemail management command (see Invoking management commands for instructions how to invoke it in different environments).

HTTP proxy¶

Weblate does execute VCS commands and those accept proxy configuration from environment. The recommended approach is to define proxy settings in settings.py:

import os
os.environ['http_proxy'] = "http://proxy.example.com:8080"
os.environ['HTTPS_PROXY'] = "http://proxy.example.com:8080"

See also

Proxy Environment Variables

Adjusting configuration¶

See also

Sample configuration

Copy weblate/settings_example.py to weblate/settings.py and adjust it to match your setup. You will probably want to adjust the following options:

ADMINS

List of site administrators to receive notifications when something goes wrong, for example notifications on failed merges, or Django errors.

See also

ADMINS

ALLOWED_HOSTS

If you are running Django 1.5 or newer, you need to set this to list the hosts your site is supposed to serve. For example:
ALLOWED_HOSTS = ['demo.weblate.org']
See also

ALLOWED_HOSTS

SESSION_ENGINE

Configure how your sessions will be stored. In case you keep the default database backend engine, you should schedule: ./manage.py clearsessions to remove stale session data from the database.

If you are using Redis as cache (see Enable caching) it is recommended to use it for sessions as well:
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
See also

Configuring the session engine, SESSION_ENGINE

DATABASES

Connectivity to database server, please check Django’s documentation for more details.

See also

Database setup for Weblate, DATABASES, Databases

DEBUG

Disable this for any production server. With debug mode enabled, Django will show backtraces in case of error to users, when you disable it, errors will be sent per e-mail to ADMINS (see above).

Debug mode also slows down Weblate, as Django stores much more info internally in this case.

See also

DEBUG,

DEFAULT_FROM_EMAIL

Email sender address for outgoing e-mail, for example registration e-mails.

See also

DEFAULT_FROM_EMAIL,

SECRET_KEY

Key used by Django to sign some info in cookies, see Django secret key for more info.

SERVER_EMAIL

Email used as sender address for sending e-mails to the administrator, for example notifications on failed merges.

See also

SERVER_EMAIL

Filling up the database¶

After your configuration is ready, you can run ./manage.py migrate to create the database structure. Now you should be able to create translation projects using the admin interface.

In case you want to run an installation non interactively, you can use ./manage.py migrate --noinput, and then create an admin user using createadmin command.

You should also log in to the admin interface (on /admin/ URL) and adjust the default sitename to match your domain by clicking on Sites and once there, change the example.com record to match your real domain name.

Once you are done, you should also check the Performance report in the admin interface, which will give you hints of potential non optimal configuration on your site.

Production setup¶

For a production setup you should carry out adjustments described in the following sections. The most critical settings will trigger a warning, which is indicated by a red exclamation mark in the top bar if logged in as a superuser:

It is also recommended to inspect checks triggered by Django (though you might not need to fix all of them):

./manage.py check --deploy

See also

Deployment checklist

Disable debug mode¶

Disable Django’s debug mode (DEBUG) by:

DEBUG = False

With debug mode on, Django stores all executed queries and shows users backtraces of errors, which is not desired in a production setup.

See also

Adjusting configuration

Properly configure admins¶

Set the correct admin addresses to the ADMINS setting to defining who will receive e-mails in case something goes wrong on the server, for example:

ADMINS = (
    ('Your Name', 'your_email@example.com'),
)

See also

Adjusting configuration

Set correct sitename¶

Adjust sitename in the admin interface, otherwise links in RSS or registration e-mails will not work.

Please open the admin interface and edit the default sitename and domain under the Sites › Sites (or do it directly at the /admin/sites/site/1/ URL under your Weblate installation). You have to change the Domain name to match your setup.

Note

This setting should only contain the domain name. For configuring protocol, (enabling HTTPS) use ENABLE_HTTPS and for changing URL, use URL_PREFIX.

Alternatively, you can set the site name from the commandline using changesite. For example, when using the built-in server:

./manage.py changesite --set-name 127.0.0.1:8000

For a production site, you want something like:

./manage.py changesite --set-name weblate.example.com

Correctly configure HTTPS¶

It is strongly recommended to run Weblate using the encrypted HTTPS protocol. After enabling it, you should set ENABLE_HTTPS in the settings, which also adjusts several other related Django settings in the example configuration.

You might want to set up HSTS as well, see SSL/HTTPS for more details.

Use a powerful database engine¶

Please use PostgreSQL for a production environment, see Database setup for Weblate for more info.

Enable caching¶

If possible, use Redis from Django by adjusting the CACHES configuration variable, for example:

CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/0',
        # If redis is running on same host as Weblate, you might
        # want to use unix sockets instead:
        # 'LOCATION': 'unix:///var/run/redis/redis.sock?db=0',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
        }
    }
}

Avatar caching¶

In addition to caching of Django, Weblate performs caching of avatars. It is recommended to use a separate, file-backed cache for this purpose:

CACHES = {
    'default': {
        # Default caching backend setup, see above
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'unix:///var/run/redis/redis.sock?db=0',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
        }
    },
    'avatar': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': os.path.join(DATA_DIR, 'avatar-cache'),
        'TIMEOUT': 604800,
        'OPTIONS': {
            'MAX_ENTRIES': 1000,
        },
    }

Configure e-mail addresses¶

Weblate needs to send out e-mails on several occasions, and these e-mails should have a correct sender address, please configure SERVER_EMAIL and DEFAULT_FROM_EMAIL to match your environment, for example:

SERVER_EMAIL = 'admin@example.org'
DEFAULT_FROM_EMAIL = 'weblate@example.org'

Allowed hosts setup¶

Django 1.5 and newer require ALLOWED_HOSTS to hold a list of domain names your site is allowed to serve, leaving it empty will block any requests.

See also

ALLOWED_HOSTS

Django secret key¶

The SECRET_KEY setting is used by Django to sign cookies, and you should really generate your own value rather than using the one from the example setup.

You can generate a new key using weblate/examples/generate-secret-key shipped with Weblate.

See also

SECRET_KEY

Home directory¶

Changed in version 2.1: This is no longer required, Weblate now stores all its data in DATA_DIR.

The home directory for the user running Weblate should exist and be writable by this user. This is especially needed if you want to use SSH to access private repositories, but Git might need to access this directory as well (depending on the Git version you use).

You can change the directory used by Weblate in settings.py, for example to set it to configuration directory under the Weblate tree:

os.environ['HOME'] = os.path.join(BASE_DIR, 'configuration')

Note

On Linux, and other UNIX like systems, the path to user’s home directory is defined in /etc/passwd. Many distributions default to a non-writable directory for users used for serving web content (such as apache, www-data or wwwrun, so you either have to run Weblate under a different user, or change this setting.

See also

Accessing repositories

Template loading¶

It is recommended to use a cached template loader for Django. It caches parsed templates and avoids the need to do parsing with every single request. You can configure it using the following snippet (the loaders setting is important here):

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            os.path.join(BASE_DIR, 'templates'),
        ],
        'OPTIONS': {
            'context_processors': [
                'django.contrib.auth.context_processors.auth',
                'django.template.context_processors.debug',
                'django.template.context_processors.i18n',
                'django.template.context_processors.request',
                'django.template.context_processors.csrf',
                'django.contrib.messages.context_processors.messages',
                'weblate.trans.context_processors.weblate_context',
            ],
            'loaders': [
                ('django.template.loaders.cached.Loader', [
                    'django.template.loaders.filesystem.Loader',
                    'django.template.loaders.app_directories.Loader',
                ]),
            ],
        },
    },
]

See also

django.template.loaders.cached.Loader

Running maintenance tasks¶

For optimal performance, it is good idea to run some maintenance tasks in the background. This is now automatically done by Background tasks using Celery and covers following tasks:

Configuration health check (hourly).
Committing pending changes (hourly), see Lazy commits and commit_pending.
Updating component alerts (daily).
Update remote branches (nightly), see AUTO_UPDATE.
Translation memory backup to JSON (daily), see dump_memory.
Fulltext and database maintenance tasks (daily and weekly taks), see cleanuptrans.

Changed in version 3.2: Since version 3.2, the default way of executing these tasks is using Celery and Weblate already comes with proper configuration, see Background tasks using Celery.

Running server¶

You will need several services to run Weblate, the recommended setup consists of:

Database server (see Database setup for Weblate)
Cache server (see Enable caching)
Frontend web server for static files and SSL termination (see Serving static files)
Wsgi server for dynamic content (see Sample configuration for NGINX and uWSGI)
Celery for executing background tasks (see Background tasks using Celery)

Note

There are some dependencies between the services, for example cache and database should be running when starting up Celery or uwsgi processes.

In most cases, you will run all services on single (virtual) server, but in case your installation is heavy loaded, you can split up the services. The only limitation on this is that Celery and Wsgi servers need access to DATA_DIR.

Running web server¶

Running Weblate is not different from running any other Django based program. Django is usually executed as uWSGI or fcgi (see examples for different webservers below).

For testing purposes, you can use the built-in web server in Django:

./manage.py runserver

Warning

Do not use this in production, as this has severe performance limitations.

Serving static files¶

Changed in version 2.4: Prior to version 2.4, Weblate didn’t properly use the Django static files framework and the setup was more complex.

Django needs to collect its static files in a single directory. To do so, execute ./manage.py collectstatic --noinput. This will copy the static files into a directory specified by the STATIC_ROOT setting (this defaults to a static directory inside DATA_DIR).

It is recommended to serve static files directly from your web server, you should use that for the following paths:

/static/: Serves static files for Weblate and the admin interface (from defined by STATIC_ROOT).
/media/: Used for user media uploads (e.g. screenshots).
/favicon.ico: Should be rewritten to rewrite a rule to serve /static/favicon.ico
/robots.txt: Should be rewritten to rewrite a rule to serve /static/robots.txt

Content security policy¶

The default Weblate configuration enables weblate.middleware.SecurityMiddleware middleware which sets security related HTTP headers like Content-Security-Policy or X-XSS-Protection. These are by default set up to work with Weblate and it’s configuration, but this might clash with your customization. If that is the case, it is recommended to disable this middleware and set these headers manually.

Sample configuration for Apache¶

The following configuration runs Weblate as WSGI, you need to have enabled mod_wsgi (available as weblate/examples/apache.conf):

#
# VirtualHost for weblate
#
# This example assumes Weblate is installed in /usr/share/weblate
#
# If using virtualenv, you need to add it to search path as well:
# WSGIPythonPath /usr/share/weblate:/path/to/your/venv/lib/python3.7/site-packages
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/robots.txt
    Alias /robots.txt /var/lib/weblate/static/robots.txt
    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /var/lib/weblate/static/favicon.ico

    # DATA_DIR/static/
    Alias /static/ /var/lib/weblate/static/
    <Directory /var/lib/weblate/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /media/ /var/lib/weblate/media/
    <Directory /var/lib/weblate/media/>
        Require all granted
    </Directory>

    WSGIDaemonProcess weblate.example.org python-path=/usr/share/weblate
    WSGIProcessGroup weblate.example.org
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias / /usr/share/weblate/weblate/wsgi.py process-group=weblate.example.org
    WSGIPassAuthorization On

    <Directory /usr/share/weblate/weblate>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

This configuration is for Apache 2.4 and later. For earlier versions of Apache, replace Require all granted with Allow from all.

Sample configuration for Apache and Gunicorn¶

The following configuration runs Weblate in Gunicorn and Apache 2.4 (available as weblate/examples/apache.gunicorn.conf):

#
# VirtualHost for weblate using gunicorn on localhost:8000
#
# This example assumes Weblate is installed in /usr/share/weblate
#
#

<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/robots.txt
    Alias /robots.txt /var/lib/weblate/static/robots.txt
    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /var/lib/weblate/static/favicon.ico

    # DATA_DIR/static/
    Alias /static/ /var/lib/weblate/static/
    <Directory /var/lib/weblate/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /media/ /var/lib/weblate/media/
    <Directory /var/lib/weblate/media/>
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/https_cert.cert
    SSLCertificateKeyFile /etc/apache2/ssl/https_key.pem
    SSLProxyEngine On

    ProxyPass /robots.txt !
    ProxyPass /favicon.ico !
    ProxyPass /static/ !
    ProxyPass /media/ !

    ProxyPass / http://localhost:8000/
    ProxyPassReverse / http://localhost:8000/
    ProxyPreserveHost On
</VirtualHost>

See also

How to use Django with Gunicorn

Sample configuration for NGINX and uWSGI¶

To run production webserver, use the wsgi wrapper installed with Weblate (in virtual env case it is installed as ~/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py). Don’t forget to set the Python search path to your virtualenv as well (for example using virtualenv = /home/user/weblate-env in uWSGI).

The following configuration runs Weblate as uWSGI under the NGINX webserver.

Configuration for NGINX (also available as weblate/examples/weblate.nginx.conf):

server {
    listen 80;
    server_name weblate;
    root /usr/share/weblate;

    location ~ ^/favicon.ico$ {
        # DATA_DIR/static/favicon.ico
        alias /var/lib/weblate/static/favicon.ico;
        expires 30d;
    }

    location ~ ^/robots.txt$ {
        # DATA_DIR/static/robots.txt
        alias /var/lib/weblate/static/robots.txt;
        expires 30d;
    }

    location /static/ {
        # DATA_DIR/static/
        alias /var/lib/weblate/static/;
        expires 30d;
    }

    location /media/ {
        # DATA_DIR/media/
        alias /var/lib/weblate/media/;
        expires 30d;
    }

    location / {
        include uwsgi_params;
        # Needed for long running operations in admin interface
        uwsgi_read_timeout 3600;
        # Adjust based to uwsgi configuration:
        uwsgi_pass unix:///run/uwsgi/app/weblate/socket;
        # uwsgi_pass 127.0.0.1:8080;
    }
}

Configuration for uWSGI (also available as weblate/examples/weblate.uwsgi.ini):

[uwsgi]
plugins       = python
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /usr/local/lib/python3.6/dist-packages/weblate/wsgi.py

# Add path to Weblate checkout if you did not install
# Weblate by pip
# python-path   = /path/to/weblate

# In case you're using virtualenv uncomment this:
# virtualenv = /path/to/weblate/virtualenv

# Needed for OAuth/OpenID
buffer-size   = 8192

# Increase number of workers for heavily loaded sites
# workers       = 6

# Child processes do not need file descriptors
close-on-exec = true

# Avoid default 0000 umask
umask = 0022

# Run as weblate user
uid = weblate
gid = weblate

# Enable harakiri mode (kill requests after some time)
# harakiri = 3600
# harakiri-verbose = true

# Enable uWSGI stats server
# stats = :1717
# stats-http = true

# Do not log some errors caused by client disconnects
ignore-sigpipe = true
ignore-write-errors = true
disable-write-exception = true

See also

How to use Django with uWSGI

Running Weblate under path¶

Changed in version 1.3: This is supported since Weblate 1.3.

A sample Apache configuration to serve Weblate under /weblate. Again using mod_wsgi (also available as weblate/examples/apache-path.conf):

# Example Apache configuration for running Weblate under /weblate path

WSGIPythonPath /usr/share/weblate
# If using virtualenv, you need to add it to search path as well:
# WSGIPythonPath /usr/share/weblate:/path/to/your/venv/lib/python3.7/site-packages
<VirtualHost *:80>
    ServerAdmin admin@image.weblate.org
    ServerName image.weblate.org

    # DATA_DIR/static/robots.txt
    Alias /weblate/robots.txt /var/lib/weblate/static/robots.txt
    # DATA_DIR/static/favicon.ico
    Alias /weblate/favicon.ico /var/lib/weblate/static/favicon.ico

    # DATA_DIR/static/
    Alias /weblate/static/ /var/lib/weblate/static/
    <Directory /var/lib/weblate/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /weblate/media/ /var/lib/weblate/media/
    <Directory /var/lib/weblate/media/>
        Require all granted
    </Directory>

    WSGIScriptAlias /weblate /usr/share/weblate/weblate/wsgi.py/weblate
    WSGIPassAuthorization On

    <Directory /usr/share/weblate/weblate>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

Additionally, you will have to adjust weblate/settings.py:

URL_PREFIX = '/weblate'

Background tasks using Celery¶

New in version 3.2.

Weblate uses Celery to process background tasks. The example settings come with eager configuration, which does process all tasks in place, but you want to change this to something more reasonable for a production setup.

A typical setup using Redis as a backend looks like this:

CELERY_TASK_ALWAYS_EAGER = False
CELERY_BROKER_URL = 'redis://localhost:6379'
CELERY_RESULT_BACKEND = CELERY_BROKER_URL

You should also start the Celery worker to process the tasks and start scheduled tasks, this can be done directly on the command line (which is mostly useful when debugging or developing):

./weblate/examples/celery start
./weblate/examples/celery stop

Most likely you will want to run Celery as a daemon and that is covered by Daemonization. For the most common Linux setup using systemd, you can use the example files shipped in the examples folder listed below.

Systemd unit to be placed as /etc/systemd/system/celery-weblate.service:

[Unit]
Description=Celery Service (Weblate)
After=network.target

[Service]
Type=forking
User=weblate
Group=weblate
EnvironmentFile=/etc/default/celery-weblate
WorkingDirectory=/home/weblate
PermissionsStartOnly=true
ExecStartPre=/bin/mkdir -p /var/run/celery
ExecStartPre=/bin/chown -R weblate /var/run/celery/
ExecStartPre=/bin/mkdir -p /var/log/celery
ExecStartPre=/bin/chown -R weblate /var/log/celery/
ExecStart=/bin/sh -c '${CELERY_BIN} multi start ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'
ExecStop=/bin/sh -c '${CELERY_BIN} multi stopwait ${CELERYD_NODES} \
  --pidfile=${CELERYD_PID_FILE}'
ExecReload=/bin/sh -c '${CELERY_BIN} multi restart ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'

[Install]
WantedBy=multi-user.target

Environment configuration to be placed as /etc/default/celery-weblate:

# Name of nodes to start
CELERYD_NODES="celery notify search memory"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/usr/local/bin/celery"

# App instance to use
# comment out this line if you don't use an app
CELERY_APP="weblate"

# Extra command-line arguments to the worker,
# increase concurency if you get weblate.E019
CELERYD_OPTS="--beat:celery --concurrency:celery=4 --queues:celery=celery --prefetch-multiplier:celery=4 \
--concurrency:notify=4 --queues:notify=notify --prefetch-multiplier:notify=4 \
--concurrency:search=1 --queues:search=search --prefetch-multiplier:search=2000 \
--concurrency:memory=1 --queues:memory=memory --prefetch-multiplier:memory=2000"

# Logging configuration
# - %n will be replaced with the first part of the nodename.
# - %I will be replaced with the current child process index
#   and is important when using the prefork pool to avoid race conditions.
CELERYD_PID_FILE="/var/run/celery/weblate-%n.pid"
CELERYD_LOG_FILE="/var/log/celery/weblate-%n%I.log"
CELERYD_LOG_LEVEL="INFO"

# Internal Weblate variable to indicate we're running inside Celery
CELERY_WORKER_RUNNING="1"

Logrotate configuration to be placed as /etc/logrotate.d/celery:

/var/log/celery/*.log {
        weekly
        missingok
        rotate 12
        compress
        notifempty
}

Weblate comes with built-in setup for scheduled tasks. You can however define additional tasks in settings.py, for example see Lazy commits.

You can use celery_queues to see current length of Celery task queues. In case the queue will get too long, you will also get configuration error in the admin interface.

Note

The Celery process has to be executed under the same user as Weblate and the WSGI process, otherwise files in the DATA_DIR will be stored with mixed ownership, leading to runtime issues.

Warning

The Celery errors are by default only logged into Celery log and are not visible to user. In case you want to have overview on such failures, it is recommended to configure Collecting error reports.

Monitoring Weblate¶

Weblate provides the /healthz/ URL to be used in simple health checks, for example using Kubernetes.

Collecting error reports¶

Weblate, as any other software, can fail. In order to collect useful failure states we recommend to use third party services to collect such information. This is especially useful in case of failing Celery tasks, which would otherwise only report error to the logs and you won’t get notified on them. Weblate has support for the following services:

Sentry¶

Weblate has built in support for Sentry. To use it, it’s enough to follow instructions for Sentry for Python.

In short, you need to adjust settings.py:

import raven

# Add raven to apps:
INSTALLED_APPS = (
    # ... other app classes ...
    'raven.contrib.django.raven_compat',
)


RAVEN_CONFIG = {
    'dsn': 'https://id:key@your.sentry.example.com/',
    # Setting public_dsn will allow collecting user feedback on errors
    'public_dsn': 'https://id@your.sentry.example.com/',
    # If you are using git, you can also automatically configure the
    # release based on the git info.
    'release': raven.fetch_git_sha(BASE_DIR),
}

Rollbar¶

Weblate has built-in support for Rollbar. To use it, it’s enough to follow instructions for Rollbar notifier for Python.

In short, you need to adjust settings.py:

# Add rollbar as last middleware:
MIDDLEWARE = [
    # … other middleware classes …
    'rollbar.contrib.django.middleware.RollbarNotifierMiddleware',
]

# Configure client access
ROLLBAR = {
    'access_token': 'POST_SERVER_ITEM_ACCESS_TOKEN',
    'client_token': 'POST_CLIENT_ITEM_ACCESS_TOKEN',
    'environment': 'development' if DEBUG else 'production',
    'branch': 'master',
    'root': '/absolute/path/to/code/root',
}

Everything else is integrated automatically, you will now collect both server and client side errors.

Migrating Weblate to another server¶

Migrating Weblate to another server should be pretty easy, however it stores data in few locations which you should migrate carefully. The best approach is to stop Weblate for the migration.

Migrating database¶

Depending on your database backend, you might have several options to migrate the database. The most straightforward one is to dump the database on one server and import it on the new one. Alternatively you can use replication in case your database supports it.

The best approach is to use database native tools, as they are usually the most effective (e.g. mysqldump or pg_dump). If you want to migrate between different databases, the only option might be to use Django management to dump and import the database:

# Export current data
./manage.py dumpdata > /tmp/weblate.dump
# Import dump
./manage.py loaddata /tmp/weblate.dump

Migrating VCS repositories¶

The VCS repositories stored under DATA_DIR need to be migrated as well. You can simply copy them or use rsync to do the migration more effectively.

Migrating fulltext index¶

For the fulltext index, (stored in DATA_DIR) it is better not to migrate it, but rather generate a fresh one using rebuild_index.

Other notes¶

Don’t forget to move other services Weblate might have been using like Redis, Cron jobs or custom authentication backends.

Weblate deployments¶

This is an overview of the supported deployment technologies.

Running Weblate with Docker¶

With dockerized Weblate deployment you can get your personal Weblate instance up an running in seconds. All of Weblate’s dependencies are already included. PostgreSQL is set up as the default database.

Deployment¶

The following examples assume you have a working Docker environment, with docker-compose installed. Please check the Docker documentation for instructions.

Clone the weblate-docker repo:

git clone https://github.com/WeblateOrg/docker-compose.git weblate-docker
cd weblate-docker

Create a docker-compose.override.yml file with your settings. See Docker environment variables for full list of environment variables.

version: '3'
services:
  weblate:
    ports:
      - 80:8080
    environment:
      WEBLATE_EMAIL_HOST: smtp.example.com
      WEBLATE_EMAIL_HOST_USER: user
      WEBLATE_EMAIL_HOST_PASSWORD: pass
      WEBLATE_SERVER_EMAIL: weblate@example.com
      WEBLATE_DEFAULT_FROM_EMAIL: weblate@example.com
      WEBLATE_ALLOWED_HOSTS: weblate.example.com,localhost
      WEBLATE_ADMIN_PASSWORD: password for the admin user
      WEBLATE_ADMIN_EMAIL: weblate.admin@example.com

Note

If WEBLATE_ADMIN_PASSWORD is not set, the admin user is created with a random password shown on first startup.

Append ‘,localhost’ to WEBLATE_ALLOWED_HOSTS to be able to access locally for testing.

You may also need to edit the docker-compose.yml file and change the default port from 80 if you already have a web server running on your local machine

Start Weblate containers:
```
docker-compose up
```

Enjoy your Weblate deployment, it’s accessible on port 80 of the weblate container.

Changed in version 2.15-2: The setup has changed recently, priorly there was separate web server container, since 2.15-2 the web server is embedded in the Weblate container.

Changed in version 3.7.1-6: In July 2019 (starting with the 3.7.1-6 tag), the containers is not running as root. As a consequence this has lead to changed exposed port from 80 to 8080.

See also

Invoking management commands

Docker container with HTTPS support¶

Please see Deployment for generic deployment instructions. To add a reverse HTTPS proxy an additional Docker container is required, https-portal will be used. This is made use of in the docker-compose-https.yml file. Then create a docker-compose-https.override.yml file with your settings:

version: '3'
services:
  weblate:
    environment:
      WEBLATE_EMAIL_HOST: smtp.example.com
      WEBLATE_EMAIL_HOST_USER: user
      WEBLATE_EMAIL_HOST_PASSWORD: pass
      WEBLATE_ALLOWED_HOSTS: weblate.example.com
      WEBLATE_ADMIN_PASSWORD: password for admin user
  https-portal:
    environment:
      DOMAINS: 'weblate.example.com -> http://weblate:8080'

Whenever invoking docker-compose you need to pass both files to it, and then do:

docker-compose -f docker-compose-https.yml -f docker-compose-https.override.yml build
docker-compose -f docker-compose-https.yml -f docker-compose-https.override.yml up

Upgrading the Docker container¶

Usually it is good idea to only update the Weblate container and keep the PostgreSQL container at the version you have, as upgrading PostgreSQL is quite painful and in most cases does not bring many benefits.

You can do this by sticking with the existing docker-compose and just pull the latest images and then restart:

docker-compose stop
docker-compose pull
docker-compose up

The Weblate database should be automatically migrated on first startup, and there should be no need for additional manual actions.

Note

Upgrades across 3.0 are not supported by Weblate. If you are on 2.x series and want to upgrade to 3.x, first upgrade to the latest 3.0.1-x (at time of writing this it is the 3.0.1-7) image, which will do the migration and then continue upgrading to newer versions.

Docker environment variables¶

Many of Weblate’s Configuration can be set in the Docker container using environment variables:

Generic settings¶

WEBLATE_DEBUG¶

Configures Django debug mode using DEBUG.

Example:

environment:
  WEBLATE_DEBUG: 1

See also

Disable debug mode.

WEBLATE_LOGLEVEL¶: Configures the logging verbosity.

WEBLATE_SITE_TITLE¶: Configures the site-title shown on the heading of all pages.

WEBLATE_ADMIN_NAME¶

WEBLATE_ADMIN_EMAIL¶

Configures the site-admin’s name and e-mail.

Example:

environment:
  WEBLATE_ADMIN_NAME: Weblate admin
  WEBLATE_ADMIN_EMAIL: noreply@example.com

See also

Properly configure admins

WEBLATE_ADMIN_PASSWORD¶: Sets the password for the admin user. If not set, the admin user is created with a random password shown on first startup.

Changed in version 2.9: Since version 2.9, the admin user is adjusted on every container startup to match WEBLATE_ADMIN_PASSWORD, WEBLATE_ADMIN_NAME and WEBLATE_ADMIN_EMAIL.

WEBLATE_SERVER_EMAIL¶

WEBLATE_DEFAULT_FROM_EMAIL¶: Configures the address for outgoing e-mails.

See also

Configure e-mail addresses

WEBLATE_ALLOWED_HOSTS¶

Configures allowed HTTP hostnames using ALLOWED_HOSTS and sets sitename to the first one.

Example:

environment:
  WEBLATE_ALLOWED_HOSTS: weblate.example.com,example.com

WEBLATE_SECRET_KEY¶: Configures the secret used by Django for cookie signing.

Deprecated since version 2.9: The secret is now generated automatically on first startup, there is no need to set it manually.

See also

Django secret key

WEBLATE_REGISTRATION_OPEN¶

Configures whether registrations are open by toggling REGISTRATION_OPEN.

Example:

environment:
  WEBLATE_REGISTRATION_OPEN: 0

WEBLATE_TIME_ZONE¶

Configures the used time zone in Weblate, see TIME_ZONE.

Note

To change the time zone of the Docker container itself, use the TZ environment variable.

Example:

environment:
  WEBLATE_TIME_ZONE: Europe/Prague

WEBLATE_ENABLE_HTTPS¶

Makes Weblate assume it is operated behind a reverse HTTPS proxy, it makes Weblate use HTTPS in e-mail and API links or set secure flags on cookies.

Note

This does not make the Weblate container accept HTTPS connections, you need to use a standalone reverse HTTPS proxy, see Docker container with HTTPS support for example.

Example:

environment:
  WEBLATE_ENABLE_HTTPS: 1

See also

Database setup for Weblate

WEBLATE_IP_PROXY_HEADER¶

Lets Weblate fetch the IP address from any given HTTP header. Use this when using a reverse proxy in front of the Weblate container.

Enables IP_BEHIND_REVERSE_PROXY and sets IP_PROXY_HEADER.

Note

The format must conform to Django’s expectations. Django transforms raw HTTP header names as follows:

converts all characters to uppercase
replaces any hyphens with underscores
prepends HTTP_ prefix

So X-Forwarded-For would be mapped to HTTP_X_FORWARDED_FOR.

Example:

environment:
  WEBLATE_IP_PROXY_HEADER: HTTP_X_FORWARDED_FOR

WEBLATE_REQUIRE_LOGIN¶

Configures login required for the whole of the Weblate installation using LOGIN_REQUIRED_URLS.

Example:

environment:
  WEBLATE_REQUIRE_LOGIN: 1

WEBLATE_LOGIN_REQUIRED_URLS_EXCEPTIONS¶: Adds URL exceptions for login required for the whole Weblate installation using LOGIN_REQUIRED_URLS_EXCEPTIONS.

WEBLATE_GOOGLE_ANALYTICS_ID¶: Configures ID for Google Analytics by changing GOOGLE_ANALYTICS_ID.

WEBLATE_GITHUB_USERNAME¶: Configures GitHub username for GitHub pull-requests by changing GITHUB_USERNAME.

See also

Pushing changes to GitHub as pull request, Setting up hub

WEBLATE_SIMPLIFY_LANGUAGES¶: Configures the language simplification policy, see SIMPLIFY_LANGUAGES.

WEBLATE_AKISMET_API_KEY¶: Configures the Akismet API key, see AKISMET_API_KEY.

WEBLATE_GPG_IDENTITY¶: Configures GPG signing of commits, see WEBLATE_GPG_IDENTITY.

See also

Signing Git commits by GnuPG

Machine translation settings¶

WEBLATE_MT_DEEPL_KEY¶: Enables DeepL machine translation and sets MT_DEEPL_KEY

WEBLATE_MT_GOOGLE_KEY¶: Enables Google Translate and sets MT_GOOGLE_KEY

WEBLATE_MT_MICROSOFT_COGNITIVE_KEY¶: Enables Microsoft Cognitive Services Translator and sets MT_MICROSOFT_COGNITIVE_KEY

WEBLATE_MT_MYMEMORY_ENABLED¶: Enables MyMemory machine translation and sets MT_MYMEMORY_EMAIL to WEBLATE_ADMIN_EMAIL.

WEBLATE_MT_GLOSBE_ENABLED¶: Enables Glosbe machine translation.

Authentication settings¶

LDAP¶

WEBLATE_AUTH_LDAP_SERVER_URI¶

WEBLATE_AUTH_LDAP_USER_DN_TEMPLATE¶

WEBLATE_AUTH_LDAP_USER_ATTR_MAP¶

WEBLATE_AUTH_LDAP_BIND_DN¶

WEBLATE_AUTH_LDAP_BIND_PASSWORD¶

LDAP authentication configuration.

Example:

environment:
  WEBLATE_AUTH_LDAP_SERVER_URI: ldap://ldap.example.org
  WEBLATE_AUTH_LDAP_USER_DN_TEMPLATE: uid=%(user)s,ou=People,dc=example,dc=net
  # map weblate 'full_name' to ldap 'name' and weblate 'email' attribute to 'mail' ldap attribute.
  # another example that can be used with OpenLDAP: 'full_name:cn,email:mail'
  WEBLATE_AUTH_LDAP_USER_ATTR_MAP: full_name:name,email:mail

See also

LDAP authentication

GitHub¶

WEBLATE_SOCIAL_AUTH_GITHUB_KEY¶

WEBLATE_SOCIAL_AUTH_GITHUB_SECRET¶: Enables GitHub authentication.

BitBucket¶

WEBLATE_SOCIAL_AUTH_BITBUCKET_KEY¶

WEBLATE_SOCIAL_AUTH_BITBUCKET_SECRET¶: Enables Bitbucket authentication.

Facebook¶

WEBLATE_SOCIAL_AUTH_FACEBOOK_KEY¶

WEBLATE_SOCIAL_AUTH_FACEBOOK_SECRET¶: Enables Facebook OAuth 2.

Google¶

WEBLATE_SOCIAL_AUTH_GOOGLE_OAUTH2_KEY¶

WEBLATE_SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET¶: Enables Google OAuth 2.

GitLab¶

WEBLATE_SOCIAL_AUTH_GITLAB_KEY¶

WEBLATE_SOCIAL_AUTH_GITLAB_SECRET¶

WEBLATE_SOCIAL_AUTH_GITLAB_API_URL¶: Enables GitLab OAuth 2.

Azure Active Directory¶

WEBLATE_SOCIAL_AUTH_AZUREAD_OAUTH2_KEY¶

WEBLATE_SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET¶: Enables Azure Active Directory authentication, see Microsoft Azure Active Directory.

Azure Active Directory with Tenant support¶

WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY¶

WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET¶

WEBLATE_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID¶: Enables Azure Active Directory authentication with Tenant support, see Microsoft Azure Active Directory.

Linux vendors¶

You can enable authentication using Linux vendors authentication services by setting following variables to any value.

WEBLATE_SOCIAL_AUTH_FEDORA¶

WEBLATE_SOCIAL_AUTH_OPENSUSE¶

WEBLATE_SOCIAL_AUTH_UBUNTU¶

Other authentication settings¶

WEBLATE_NO_EMAIL_AUTH¶: Disables e-mail authentication when set to any value.

PostgreSQL database setup¶

The database is created by docker-compose.yml, so these settings affect both Weblate and PostgreSQL containers.

See also

POSTGRES_PASSWORD¶: PostgreSQL password.

POSTGRES_USER¶: PostgreSQL username.

POSTGRES_DATABASE¶: PostgreSQL database name.

POSTGRES_HOST¶: PostgreSQL server hostname or IP address. Defaults to database.

POSTGRES_PORT¶: PostgreSQL server port. Defaults to none (uses the default value).

POSTGRES_SSL_MODE¶: Configure how PostgreSQL handles SSL in connection to the server, for possible choices see SSL Mode Descriptions

Caching server setup¶

Using Redis is strongly recommended by Weblate and you have to provide a Redis instance when running Weblate in Docker.

See also

Enable caching

REDIS_HOST¶: The Redis server hostname or IP address. Defaults to cache.

REDIS_PORT¶: The Redis server port. Defaults to 6379.

REDIS_DB¶: The Redis database number, defaults to 1.

REDIS_PASSWORD¶: The Redis server password, not used by default.

Email server setup¶

To make outgoing e-mail work, you need to provide a mail server.

See also

Configuring outgoing e-mail

WEBLATE_EMAIL_HOST¶: Mail server, the server has to listen on port 587 and understand TLS.

See also

EMAIL_HOST

WEBLATE_EMAIL_PORT¶: Mail server port. Use if your cloud provider or ISP blocks outgoing connections on port 587.

See also

EMAIL_PORT

WEBLATE_EMAIL_HOST_USER¶: Email authentication user, do NOT use quotes here.

See also

EMAIL_HOST_USER

WEBLATE_EMAIL_HOST_PASSWORD¶: Email authentication password, do NOT use quotes here.

See also

EMAIL_HOST_PASSWORD

WEBLATE_EMAIL_USE_SSL¶: Whether to use an implicit TLS (secure) connection when talking to the SMTP server. In most e-mail documentation, this type of TLS connection is referred to as SSL. It is generally used on port 465. If you are experiencing problems, see the explicit TLS setting WEBLATE_EMAIL_USE_TLS.

See also

EMAIL_USE_SSL

WEBLATE_EMAIL_USE_TLS¶: Whether to use a TLS (secure) connection when talking to the SMTP server. This is used for explicit TLS connections, generally on port 587. If you are experiencing connections that hang, see the implicit TLS setting WEBLATE_EMAIL_USE_SSL.

See also

EMAIL_USE_TLS

Error reporting¶

It is recommended to collect errors from the installation in a systematic way, see Collecting error reports.

To enable support for Rollbar, set the following:

ROLLBAR_KEY¶: Your Rollbar post server access token.

ROLLBAR_ENVIRONMENT¶: Your Rollbar environment, defaults to production.

To enable support for Sentry, set following:

SENTRY_DSN¶: Your Sentry DSN.

SENTRY_PUBLIC_DSN¶: Your Sentry public DSN.

SENTRY_ENVIRONMENT¶: Your Sentry environment, defaults to production.

Further configuration customization¶

You can additionally override the configuration in /app/data/settings-override.py. This is executed after all environment settings are loaded, so it gets completely set up, and can be used to customize anything.

Hub setup¶

In order to use the GitHub’s pull-request feature, you must initialize hub configuration by entering the Weblate container and executing an arbitrary Hub command. For example:

docker-compose exec --user weblate weblate bash
cd
HOME=/app/data/home hub clone octocat/Spoon-Knife

The username passed for credentials must be the same as GITHUB_USERNAME.

Select your machine - local or cloud providers¶

With docker-machine you can create your Weblate deployment either on your local machine, or on any large number of cloud-based deployments on e.g. Amazon AWS, Greenhost, and many other providers.

Running Weblate on OpenShift 2¶

This repository contains a configuration for the OpenShift platform as a service product, which facilitates easy installation of Weblate on OpenShift variants (see https://www.openshift.com/ and https://www.okd.io/).

Prerequisites¶

OpenShift Account

You need an account on OpenShift Online (https://www.openshift.com/) or another OpenShift installation you have access to.

You can register a gratis account on OpenShift Online, which allows you to host up to 3 programs gratis.
OpenShift Client Tools

In order to follow the examples given in this documentation, you need to have the OpenShift Client Tools (RHC) installed: https://docs.openshift.com/online/cli_reference/get_started_cli.html

While there are other possibilities to create and configure OpenShift programs, this documentation is based on the OpenShift Client Tools (RHC) because they provide a consistent interface for all described operations.

Installation¶

You can install Weblate on OpenShift directly from Weblate’s GitHub repository with the following command:

# Install Git from the development master branch
rhc -aweblate app create -t python-2.7 --from-code https://github.com/WeblateOrg/weblate.git --no-git

# Install Weblate release
rhc -aweblate app create -t python-2.7 --from-code https://github.com/WeblateOrg/weblate.git#weblate-3.8 --no-git

The -a option defines the name of your weblate installation, weblate in this instance. Feel free to specify a different name.

The above example installs the latest development version, you can optionally specify tag identifier to the right of the # sign to identify the version of Weblate to install. A list of available versions is available here: https://github.com/WeblateOrg/weblate/tags.

The --no-git option skips the creation of a local Git repository.

You can also specify which database you want to use:

# For MySQL
rhc -aweblate app create -t python-2.7 -t mysql-5.5 --from-code https://github.com/WeblateOrg/weblate.git --no-git

# For PostgreSQL
rhc -aweblate app create -t python-2.7 -t postgresql-9.2 --from-code https://github.com/WeblateOrg/weblate.git --no-git

Default Configuration¶

After installation on OpenShift, Weblate is ready for use and, preconfigured as follows:

SQLite embedded database (DATABASES)
Random admin password
Random Django secret key (SECRET_KEY)
Committing of pending changes if the Cron cartridge is installed (commit_pending)
Weblate machine translations for suggestions, based on previous translations (MT_SERVICES)
Weblate directories (STATIC_ROOT, DATA_DIR, avatar cache) set according to OpenShift requirements/conventions.
Django sitename and ALLOWED_HOSTS set to DNS name of your OpenShift program
Email sender addresses set to no-reply@<OPENSHIFT_CLOUD_DOMAIN>, where <OPENSHIFT_CLOUD_DOMAIN> is the domain OpenShift runs under. In case of OpenShift Online it is rhcloud.com.

See also

Customize the Weblate Configuration

Retrieve the Admin Password¶

Retrieve the generated admin password using the following command:

rhc -aweblate ssh credentials

Pending Changes¶

Weblate’s OpenShift configuration contains a Cron job which periodically commits pending changes older than a certain age (24h by default). To enable the Cron job you need to add the Cron cartridge and restart Weblate as described in the previous section. You can change the age parameter by setting the environment variable WEBLATE_PENDING_AGE to the desired number of hours, e.g.:

rhc -aweblate env set WEBLATE_PENDING_AGE=48

Customize the Weblate Configuration¶

Customize the configuration of your Weblate installation on OpenShift through the use of environment variables. Override any of Weblate’s settings documented under Configuration using rhc env set by prepending the settings name with WEBLATE_. The variable content is put into the configuration file verbatim, so it is parsed as a Python string, after replacing the environment variables in it (e.g. $PATH). To put in a literal $ you need to escape it as $$.

For example override the ADMINS setting like this:

rhc -aweblate env set WEBLATE_ADMINS='(("John Doe", "john@example.org"),)'

To change the sitetitle, do not forget to include additional quotes:

rhc -aweblate env set WEBLATE_SITE_TITLE='"Custom Title"'

The new settings will only take effect once Weblate is restarted:

rhc -aweblate app stop
rhc -aweblate app start

Restarting using rhc -aweblate app restart does not work. For security reasons only constant expressions are allowed as values. With the exception of environment variables, which can be referenced using ${ENV_VAR}. For example:

rhc -aweblate env set WEBLATE_SCRIPTS='("${OPENSHIFT_DATA_DIR}/weblate/examples/hook-unwrap-po",)'

You can check the effective settings Weblate is using by running:

rhc -aweblate ssh settings

This will also print syntax errors in your expressions. To reset a setting to its preconfigured value, just delete the corresponding environment variable:

rhc -aweblate env unset WEBLATE_ADMINS

See also

Configuration

Updating¶

It is recommended that you try updates on a clone of your Weblate installation before running the actual update. To create such a clone, run:

rhc -aweblate2 app create --from-app weblate

Visit the newly given URL with a web browser and wait for the install/update page to disappear.

You can update your Weblate installation on OpenShift directly from Weblate’s GitHub repository by executing:

rhc -aweblate2 ssh update https://github.com/WeblateOrg/weblate.git

The identifier to the right of the # sign identifies the version of Weblate to install. For a list of available versions see: https://github.com/WeblateOrg/weblate/tags. Please note that the update process will not work if you modified the Git repository of you Weblate installation. You can force an update by specifying the --force option with the update script. However any changes you made to the Git repository of your installation will be discarded:

rhc -aweblate2 ssh update --force https://github.com/WeblateOrg/weblate.git

The --force option is also needed when downgrading to an older version. Please note that only version 2.0 and newer can be installed on OpenShift, as older versions don’t include the necessary configuration files.

The update script takes care of the following update steps, as described in Generic upgrade instructions.

Install any new requirements
manage.py migrate
manage.py setupgroups –move
manage.py setuplang
manage.py rebuild_index –all
manage.py collectstatic –noinput

Bitnami Weblate stack¶

Bitnami provides a Weblate stack for many platforms at <https://bitnami.com/stack/weblate>. The setup will be adjusted during installation, see <https://bitnami.com/stack/weblate/README.txt> for more documentation.

Weblate in YunoHost¶

The self-hosting project YunoHost provides a package for Weblate. Once you have your YunoHost installation, you may install Weblate as any other application. It will provide you with a fully working stack with backup and restoration, but you may still have to edit your settings file for specific usages.

You may use your administration interface, or this button (it will bring you to your server):

It also is possible to use the commandline interface:

yunohost app install https://github.com/YunoHost-Apps/weblate_ynh

Upgrading Weblate¶

Generic upgrade instructions¶

Before upgrading, please check the current Software requirements as they might have changed. Once all requirements are installed or updated, please adjust your settings.py to match changes in the configuration (consult settings_example.py for correct values).

Always check Version specific instructions before upgrade. In case you are skipping some versions, please follow instructions for all versions you are skipping in the upgrade. Sometimes it’s better to upgrade to some intermediate version to ensure a smooth migration. Upgrading across multiple releases should work, but is not as well tested as single version upgrades.

Note

It is recommended to perform a full database backup prior to upgrade so that you can roll back the database in case upgrade fails, see Backing up and moving Weblate.

Upgrade configuration file, refer to settings_example.py or Version specific instructions for needed steps.
Upgrade database structure:
```
./manage.py migrate --noinput
```
Collect updated static files (mostly javascript and CSS):
```
./manage.py collectstatic --noinput
```
Update language definitions (this is not necessary, but heavily recommended):
```
./manage.py setuplang
```
Optionally upgrade default set of privileges definitions (you might want to add new permissions manually if you have heavily tweaked access control):
```
./manage.py setupgroups
```
If you are running version from Git, you should also regenerate locale files every time you are upgrading. You can do this by invoking:
```
./manage.py compilemessages
```
Verify that your setup is sane (see also Production setup):
```
./manage.py check --deploy
```
Restart celery worker (see Background tasks using Celery).

Version specific instructions¶

Upgrade from 2.x¶

If you are upgrading from 2.x release, always first upgrade to 3.0.1 and the continue upgrading in the 3.x series. Upgrades skipping this step are not supported and will break.

Upgrade from 3.0.1 to 3.1¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

Several no longer needed applications have been removed from INSTALLED_APPS.
The settings now recommend using several Django security features, see SSL/HTTPS.
There is new dependency on the jellyfish module.

See also

Upgrade from 3.1 to 3.2¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

Rate limiting configuration has been changed, please see Rate limiting.
Microsoft Terminology machine translation was moved to separate module and now requires zeep module.
Weblate now uses Celery for several background tasks. There are new dependencies and settings because of this. You should also run Celery worker as standalone process. See Background tasks using Celery for more information.
There are several changes in settings_example.py, most notable Celery configuration and middleware changes, please adjust your settings accordingly.

See also

Upgrade from 3.2 to 3.3¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

The DEFAULT_CUSTOM_ACL settings was replaced by DEFAULT_ACCESS_CONTROL. If you were using that please update your settings.py.
Increase required translate-toolkit version to 2.3.1.
Increase required social auth module versions (2.0.0 for social-auth-core and 3.0.0 for social-auth-app-django).
The CELERY_RESULT_BACKEND should be now configured unless you are using eager mode, see Configuration and defaults.
There is new weblate.middleware.ProxyMiddleware middleware needed if you use IP_BEHIND_REVERSE_PROXY.

See also

Upgrade from 3.3 to 3.4¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

The Celery now uses multiple queues, it is recommended to update to new worker setup which utilizes this, see Background tasks using Celery.
There is new depedency on diff-match-patch and translation-finder.

See also

Upgrade from 3.4 to 3.5¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

There are several new checks included in the CHECK_LIST.

See also

Upgrade from 3.5 to 3.6¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

The automatic detection of file format has been removed. Please adjust your translation components configuration prior to upgrade. The upgrade should be able to gracefully handle most of situations, but can fail in some corner cases.
If you have manually changed WEBLATE_FORMATS, you will have to remove AutoFormat from it.
During the upgrade, the notifications settings need to be converted. This can be lengthty operation in case you have lot of users.

See also

Upgrade from 3.6 to 3.7¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

The Celery now uses separate queue for notifications, it is recommended to update to new worker setup which utilizes this, see Background tasks using Celery.
There are new (bleach, gobject, pycairo) and updated (translation-finder) dependencies, you will now need Pango and Cairo system libraries as well, see Pango and Cairo.
There are new addons, you might want to include them in case you modified the WEBLATE_ADDONS.
There are new file formats, you might want to include them in case you modified the WEBLATE_FORMATS.
There is change in the CSRF_FAILURE_VIEW.
There is new app weblate.fonts to be included in INSTALLED_APPS.

See also

Upgrade from 3.7 to 3.8¶

Please follow Generic upgrade instructions in order to perform update.

Notable configuration or dependencies changes:

There is new app django.contrib.humanize to be included in INSTALLED_APPS.

See also

Background tasks using Celery

Upgrading from Python 2 to Python 3¶

Note

Weblate will support Python 2 util 4.0 release currently scheduled on April 2020. This is in line with Django dropping support for Python 2.

Weblate currently supports both Python 2.7 and 3.x. Upgrading existing installations is supported, but you should pay attention to some data stored on the disk as it might be incompatible between these two.

Things which might be problematic include Whoosh indices and file based caches. Fortunately these are easy to handle. Recommended upgrade steps:

Backup your Translation Memory using dump_memory:
```
./manage.py dump_memory > memory.json
```
Upgrade your installation to Python 3.
Delete Translation Memory database delete_memory:
```
./manage.py delete_memory --all
```
Restore your Translation Memory using import_memory.
```
./manage.py import_memory memory.json
```
Recreate fulltext index using rebuild_index:
```
./manage.py rebuild_index --clean --all
```
Cleanup avatar cache (if using file based) using cleanup_avatar_cache.
```
./manage.py cleanup_avatar_cache
```
It is recommended to throw away your caches.

Migrating from Pootle¶

As Weblate was originally written as replacement from Pootle, it is supported to migrate user accounts from Pootle. You can dump the users from Pootle and import them using importusers.

Backing up and moving Weblate¶

Backing up¶

Depending on what you want to save, back up the type data Weblate stores in each respective place.

Database¶

Where this is located depends on your database setup.

The database is the most important storage. Set up regular backups of your database, without it all your translation setup will be gone.

Native database backup¶

The recommended approach is to do dump of the database using database native tools such as pg_dump or mysqldump. It usually performs better than Django backup and restores complete tables with all data.

You can restore this backup in newer Weblate release, it will perform any necessary migrations when running in migrate. Please consult Upgrading Weblate on more detailed information how to peform upgrade between versions.

Django database backup¶

Alternatively you can backup database using Django’s dumpdata command. That way the backup is database agnostic and can be used in case you want to change database backend.

Prior to restoring you need to be running exactly same Weblate version as was used when doing backups. This is necessary as the database structure does change between releases and you would end up corrupting the data in some way. After installing the same version, run all database migrations using migrate.

Once this is done, some entries will be already created in the database and you will have them in the database backup as well. The recommended approach is to delete such entries manually using management shell (see Invoking management commands):

./manage.py shell
>>> from weblate.auth.models import User
>>> User.objects.get(username='anonymous').delete()

Files¶

If you have enough backup space, simply backup the whole DATA_DIR. This is safe bet even if it includes some files you don’t want. The following sections describe in detail what you should back up and what you can skip.

Dumped data for backups¶

Stored in DATA_DIR /backups.

Weblate dumps various data here, and you can include these files for more complete backups. The files are updated daily (requires a running Celery beats server, see Background tasks using Celery). Currently this includes:

Translation memory dump, in JSON format.

Version control repositories¶

Stored in DATA_DIR /vcs.

The version control repositories contain a copy of your upstream repositories with Weblate changes. If you have push on commit enabled for all your translation components, all Weblate changes are included upstream and you do not have to backup the repositories on the Weblate side. They can be cloned again from the upstream locations with no data loss.

SSH and GPG keys¶

Stored in DATA_DIR /ssh and DATA_DIR /home.

If you are using SSH or GPG keys generated by Weblate, you should back up these locations, otherwise you will loose the private keys and you will have to regenerate new ones.

User uploaded files¶

Stored in DATA_DIR /media.

You should back up user uploaded files (e.g. Visual context for strings).

Translation memory¶

Stored in DATA_DIR /memory.

It is recommended to back up this content using dump_memory in JSON-, instead of binary format, as that might eventually change (and is also incompatible going from Python 2 to Python 3). Weblate prepares this dump daily, see Dumped data for backups.

Fulltext index¶

Stored in DATA_DIR /whoosh.

It is recommended to not backup this and regenerate it from scratch on restore.

Celery tasks¶

The Celery tasks queue might contain some info, but is usually not needed for a backup. At most your will loose updates that have not yet ben processed to translation memory. It is recommended to perform the fulltext or repository updates upon restoring anyhow, so there is no problem in losing these.

See also

Restoring¶

Restore all data you have backed up.
Recreate a fulltext index using rebuild_index:
```
./manage.py rebuild_index --clean --all
```
Restore your Translation Memory using import_memory.
```
./manage.py import_memory memory.json
```
Update all repositories using updategit.
```
./manage.py updategit --all
```

Moving a Weblate installation¶

Relocatable your installation to a different system by following the backup and restore instructions above.

See also

Upgrading from Python 2 to Python 3

Authentication¶

User registration¶

The default setup for Weblate is to use python-social-auth, a form on the website to handle registration of new users. After confirming their e-mail a new user can contribute or authenticate by using one of the third party services.

You can also turn off registration of new users using REGISTRATION_OPEN.

The authentication attempts are subject to Rate limiting.

Authentication backends¶

The inbuilt solution of Django is used for authentication, including various social options to do so. Using it means you can import the user database of other Django based projects (see Migrating from Pootle).

Django can additionally be set up to authenticate against other means too.

Password authentication¶

The default settings.py comes with a reasonable set of AUTH_PASSWORD_VALIDATORS:

Passwords can’t be too similar to your other personal info.
Passwords must contain at least 6 characters.
Passwords can’t be a commonly used password.
Passwords can’t be entirely numeric.
Passwords can’t consist of a single character or only whitespace.
Passwords can’t match a password you have used in the past.

You can customize this setting to match your password policy.

Additionally you can also install django-zxcvbn-password which gives quite realistic estimates of password difficulty and allows rejecting passwords below a certain threshold.

LDAP authentication¶

LDAP authentication can be best achieved using the django-auth-ldap package. You can install it via usual means:

# Using PyPI
pip install django-auth-ldap>=1.3.0

# Using apt-get
apt-get install python-django-auth-ldap

Warning

With django-auth-ldap older than 1.3.0 the Automatic group assignments will not work properly for newly created users.

Note

There are some incompatibilities in the Python LDAP 3.1.0 module, which might prevent you from using that version. If you get error AttributeError: ‘module’ object has no attribute ‘_trace_level’, downgrading python-ldap to 3.0.0 might help.

Once you have the package installed, you can hook it into the Django authentication:

# Add LDAP backed, keep Django one if you want to be able to login
# even without LDAP for admin account
AUTHENTICATION_BACKENDS = (
    'django_auth_ldap.backend.LDAPBackend',
    'weblate.accounts.auth.WeblateUserBackend',
)

# LDAP server address
AUTH_LDAP_SERVER_URI = 'ldaps://ldap.example.net'

# DN to use for authentication
AUTH_LDAP_USER_DN_TEMPLATE = 'cn=%(user)s,o=Example'
# Depending on your LDAP server, you might use a different DN
# like:
# AUTH_LDAP_USER_DN_TEMPLATE = 'ou=users,dc=example,dc=com'

# List of attributes to import from LDAP upon login
# Weblate stores full name of the user in the full_name attribute
AUTH_LDAP_USER_ATTR_MAP = {
    'full_name': 'name',
    # Use the following if your LDAP server does not have full name
    # Weblate will merge them later
    # 'first_name': 'givenName',
    # 'last_name': 'sn',
    # Email is required for Weblate (used in VCS commits)
    'email': 'mail',
}

If you can not use direct bind for authentication, you will need to use search, and provide a user to bind for the search. For example:

import ldap
from django_auth_ldap.config import LDAPSearch

AUTH_LDAP_BIND_DN = ""
AUTH_LDAP_BIND_PASSWORD = ""
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=users,dc=example,dc=com",
    ldap.SCOPE_SUBTREE, "(uid=%(user)s)")

Note

You should remove 'social_core.backends.email.EmailAuth' from the AUTHENTICATION_BACKENDS setting, otherwise users will be able to set their password in Weblate, and authenticate using that. Keeping 'weblate.accounts.auth.WeblateUserBackend' is still needed in order to make permissions and facilitate anonymous users. It will also allow you to log in using a local admin account, if you have created it (e.g. by using createadmin).

CAS authentication¶

CAS authentication can be achieved using a package such as django-cas-ng.

Step one is disclosing the e-mail field of the user via CAS. This has to be configured on the CAS server itself, and requires you run at least CAS v2 since CAS v1 doesn’t support attributes at all.

Step two is updating Weblate to use your CAS server and attributes.

To install django-cas-ng:

pip install django-cas-ng

Once you have the package installed you can hook it up to the Django authentication system by modifying the settings.py file:

# Add CAS backed, keep the Django one if you want to be able to log in
# even without LDAP for the admin account
AUTHENTICATION_BACKENDS = (
    'django_cas_ng.backends.CASBackend',
    'weblate.accounts.auth.WeblateUserBackend',
)

# CAS server address
CAS_SERVER_URL = 'https://cas.example.net/cas/'

# Add django_cas_ng somewhere in the list of INSTALLED_APPS
INSTALLED_APPS = (
    ...,
    'django_cas_ng'
)

Finally, a signal can be used to map the e-mail field to the user object. For this to work you have to import the signal from the django-cas-ng package and connect your code with this signal. Doing this in settings file can cause problems, therefore it’s suggested to put it:

In your app config’s django.apps.AppConfig.ready() method (Django 1.7 and above)
At the end of your models.py file (Django 1.6 and below)
In the project’s urls.py file (when no models exist)

from django_cas_ng.signals import cas_user_authenticated
from django.dispatch import receiver
@receiver(cas_user_authenticated)
def update_user_email_address(sender, user=None, attributes=None, **kwargs):
    # If your CAS server does not always include the email attribute
    # you can wrap the next two lines of code in a try/catch block.
    user.email = attributes['email']
    user.save()

See also

Django CAS NG

Configuring third party Django authentication¶

Generally any Django authentication plugin should work with Weblate. Just follow the instructions for the plugin, just remember to keep the Weblate user backend installed.

See also

LDAP authentication, CAS authentication

Typically the installation will consist of adding an authentication backend to AUTHENTICATION_BACKENDS and installing an authentication app (if there is any) into INSTALLED_APPS:

AUTHENTICATION_BACKENDS = (
    # Add authentication backend here
    'weblate.accounts.auth.WeblateUserBackend',
)

INSTALLED_APPS = (
    ...
    'weblate',
    # Install authentication app here
)

Access control¶

Changed in version 3.0: Before Weblate 3.0, the privilege system was based on Django, but is now specifically built for Weblate. If you are using an older version, please the consult documentation for that version, the information here will not apply.

Weblate comes with a fine grained privilege system to assign user permissions for the whole instance, or in a limited scope.

The permission system based on groups and roles, where roles define a set of permissions, and groups assign them to users and translations, see Users, roles, groups and permissions for more details.

After installation a default set of groups is created, and you can use those to assign users roles for the whole instance (see Default groups and roles). Additionally when Per project access control is turned on, you can assign users to specific translation projects. More fine-grained configuration can be achieved using Custom access control

Common setups¶

Locking down Weblate¶

To completely lock down your Weblate installation, you can use LOGIN_REQUIRED_URLS to force users to log in and REGISTRATION_OPEN to prevent new registrations.

Site wide permissions¶

To manage permissions for a whole instance, just add users to Users (this is done by default using the Automatic group assignments), Reviewers and Managers groups. Keep all projects configured as Public (see Per project access control).

Per project permissions¶

Set your projects to Protected or Private, and manage users per project in the Weblate interface.

Adding permissions to languages, projects or component sets¶

You can additionally grant permissions to any user based on project, language or a component set. To achieve this, create a new group (e.g. Czech translators) and configure it for a given resource. Any assigned permissions will be granted to members of that group for selected resources.

This will work just fine without additional setup, if using per project permissions. For permissions on the whole instance, you will probably also want to remove these permissions from the Users group, or change automatic assignment of all users to that group (see Automatic group assignments).

Per project access control¶

Note

By enabling ACL, all users are prohibited from accessing anything within a given project, unless you add the permissions for them to do just that.

You can limit user’s access to individual projects. This feature is turned on by Access control in the configuration of each respective project. This automatically creates several groups for this project, see Predefined groups.

The following choices exist for Access control:

Public: Publicly visible and translatable
Protected: Publicly visible, but translatable only for selected users
Private: Visible and translatable only for selected users
Custom: Weblate does not manage users, see Custom access control.

To allow access to this project, you have to add the privilege either directly to the given user, or group of users in the Django admin interface, or by using user management on the project page, as described in Managing per project access control.

Note

Even with ACL turned on, some summary info will be available about your project:

Statistics for the whole instance, including counts for all projects.
Language summary for the whole instance, including counts for all projects.

Automatic group assignments¶

You can set up Weblate to automatically add users to groups based on their e-mail addresses. This automatic assignment happens only at the time of account creation.

This can be set up in the Django admin interface (in the Accounts section).

Note

The automatic group assignment for the Users and Viewers groups will always be created by Weblate upon migrations, in case you want to turn it off, simply set the regular expression to ^$, which will never match.

Users, roles, groups and permissions¶

The authentication models consist of several objects:

Permission: Individual permissions defined by Weblate. You can not assign individual permissions, this can only be done through assignment of roles.
Role: Role defines a set of permissions. This allows reuse of these sets in several places, and makes the administration easier.
User: Users can be members of several groups.
Group: Groups connect roles, users and authentication objects (projects, languages and component lists).

Permission checking¶

Whenever a permission is checked to decide whether one is able to perform a given action, the check is carried out according to scope, and the following checks are performed:

Project

Compared against the scope of the project, if not set, this matches no project.

You can use Project selection to automate inclusion of all projects.

Component list

The scope component is matched against this list, if not set, this is ignored.

Obviously this has no effect when checking access of the project scope, so you will have to grant access to view all projects in a component list by other means. By default this is achieved through the use of the Viewers group, see Default groups and roles).

Language

Compared against scope of translations, if not set, this matches no language.

You can use Language selection to automate inclusion of all languages.

Checking access to a project¶

A user has to be a member of a group linked to the project. Only membership is enough, no specific permissions are needed to access a project (this is used in the default Viewers group, see Default groups and roles).

Managing users and groups¶

All users and groups can be managed using the Django admin interface, available under /admin/ URL.

Managing per project access control¶

Note

This feature only works for ACL controlled projects, see Per project access control.

Users with the Can manage ACL rules for a project privilege (see Access control) can also manage users in projects with access control turned on through the project page. You can add users, or remove them from a project, or make them owners of it.

The user management is available in the Tools menu of a project:

See also

Per project access control

Predefined groups¶

Weblate comes with a predefined set of groups for a project, wherefrom you can assign users.

Administration: Has all permissions available in the project.

Glossary: Can manage glossary (add or remove entries, or upload).

Languages: Can manage translated languages - add or remove translations.

Screenshots: Can manage screenshots - add or remove them, and associate them to source strings.

Template: Can edit translation templates in Monolingual components and source string info.

Translate: Can translate the project, and upload translations made offline.

VCS: Can manage VCS and access the exported repository.

Review: Can approve translations during review.

Billing: Can access billing info (see Billing).

Custom access control¶

By choosing Custom as Access control, Weblate will stop managing access for a given project, and you can set up custom rules in the Django admin interface. This can be used to define more complex access control, or set up a shared access policy for all projects in a single Weblate instance. If you want to enable this for all projects by default, please configure the DEFAULT_ACCESS_CONTROL.

Warning

By turning this on, Weblate will remove all Per project access control it has created for this project. If you are doing this without admin permission from the instance, you will instantly loose your access to manage the project.

Default groups and roles¶

List of privileges¶

Billing (see Billing): View billing info [Administration, Billing]
Changes: Download changes [Administration]
Comments: Post comment [Administration, Edit source, Power user, Review strings, Translate] Delete comment [Administration]
Component: Edit component settings [Administration] Lock component, preventing it from being translated [Administration]
Glossary: Add glossary entry [Administration, Manage glossary, Power user] Edit glossary entry [Administration, Manage glossary, Power user] Delete glossary entry [Administration, Manage glossary, Power user] Upload glossary entries [Administration, Manage glossary, Power user]
Machinery: Use machine translation services [Administration, Power user]
Projects: Edit project settings [Administration] Manage project access [Administration]
Reports: Download reports [Administration]
Screenshots: Add screenshot [Administration, Manage screenshots] Edit screenshot [Administration, Manage screenshots] Delete screenshot [Administration, Manage screenshots]
Source strings: Edit source string info [Administration, Edit source]
Strings: Add new strings [Administration] Ignore failing checks [Administration, Edit source, Power user, Review strings, Translate] Edit strings [Administration, Edit source, Power user, Review strings, Translate] Review strings [Administration, Review strings] Edit string when suggestions are enforced [Administration, Review strings] Edit source strings [Administration, Edit source, Power user]
Suggestions: Accept suggestions [Administration, Edit source, Power user, Review strings, Translate] Add suggestions [Add suggestion, Administration, Edit source, Power user, Review strings, Translate] Delete suggestions [Administration] Vote on suggestions [Administration, Edit source, Power user, Review strings, Translate]
Translations: Start new translation [Administration, Manage languages, Power user] Perform automatic translation [Administration, Manage languages] Delete existing translations [Administration, Manage languages] Start translation into a new language [Administration, Manage languages]
Uploads: Define author of translation upload [Administration] Overwrite existing strings with an upload [Administration, Edit source, Power user, Review strings, Translate] Upload translation strings [Administration, Edit source, Power user, Review strings, Translate]
VCS: Access the internal repository [Access repository, Administration, Manage repository, Power user] Commit changes to the internal repository [Administration, Manage repository] Push change from the internal repository [Administration, Manage repository] Reset changes in the internal repository [Administration, Manage repository] View upstream repository location [Access repository, Administration, Manage repository, Power user] Update the internal repository [Administration, Manage repository]
Global privileges: Use management interface (global) Add language definitions (global) Manage language definitions (global) Add groups (global) Manage groups (global) Add users (global) Manage users (global) Manage whiteboard (global) Manage translation memory (global)

Note

The global privileges are not granted to any default role. These are powerful and they are quite close to the superuser status - most of them can affect all projects on your Weblate installation.

List of groups¶

The following groups are created upon installation (or after executing setupgroups):

Guests

Defines permissions for non authenticated users.

This group contains only anonymous users (see ANONYMOUS_USER_NAME).

You can remove roles from this group to limit permissions for non authenticated users.

Default roles: Add suggestion, Access repository

Viewers

This role ensures visibility of public projects for all users. By default all users are members of this group.

By default all users are members of this group, using Automatic group assignments.

Default roles: none

Users

Default group for all users.

By default all users are members of this group using Automatic group assignments.

Default roles: Power user

Reviewers

Group for reviewers (see Translation workflows).

Default roles: Review strings

Managers

Group for administrators.

Default roles: Administration

Warning

Never remove the predefined Weblate groups and users, this can lead to unexpected problems. If you do not want to use these features, just remove all privileges from them.

Translation projects¶

Translation organization¶

Weblate organizes translatable content into a tree-like structure. The bottom level object is Project configuration, which should hold all translations belonging together (for example translation of an application in several versions and/or accompanying documentation). On the level above, Component configuration, which is actually the component to translate. Here you define the VCS repository to use, and the mask of files to translate. Above Component configuration there are individual translations, handled automatically by Weblate as translation files (which match the mask defined in Component configuration) appear in the VCS repository.

All translation components need to be available as VCS repositories, and are organized in a project/component structure.

Weblate supports a wide range of translation formats (both bilingual and monolingual ones) supported by Translate Toolkit, see Supported file formats for more info.

Note

You can share cloned VCS repositories using Weblate internal URLs. Using this feature is highly recommended when you have many components sharing the same VCS. It improves performance and decreases the required disk space.

Adding translation projects and components¶

Changed in version 3.2: Since the 3.2 release the interface for adding projects and components is included in Weblate, and no longer requires you to use Django admin interface.

Changed in version 3.4: As of 3.4, the process of adding components is multi staged, with automated discovery of most parameters.

Based on your permissions, you can create new translation projects and components in Weblate. It is always permitted for superusers, and if your instance uses billing (e.g. like https://hosted.weblate.org/ see Billing), you can also create those based on your plans allowance.

You can view your current billing plan on a separate page:

The project creation can be initiated from there, or using the menu in the navigation bar, filling in basic info about the translation project to complete addition of it:

After creating the project, you are taken directly to the project page:

Creating a new translation component can be initiated via a single click there. The process of creating a component is multi-staged and automatically detects most translation parameters.

Once you have existing translation components, you can also easily add new ones for additional files or branches using same repository.

First you need to fill in name and repository location:

On the next page, you are presented with a list of discovered translatable resources:

_images/user-add-component-discovery.png

As a last step, you review the translation component info and fill in optional details:

Project configuration¶

To add a new component for translation, you need to create a translation project first. The project is like a shelf, in which real translations are stacked. All components in the same project share suggestions and their dictionary; the translations are also automatically propagated through all components in a single project (unless turned off in the component configuration).

The project has only a few attributes that informs translators of it:

Project website: URL where translators can find more info about the project.
Mailing list: Mailing list where translators can discuss or comment translations.
Translation instructions: URL to more site with more detailed instructions for translators.
Set Language-Team header: Whether Weblate should manage the Language-Team header (this is a GNU Gettext only feature right now).
Use shared translation memory: Whether to use shared translation memory, see Shared translation memory for more details.
Access control: Configure per project access control, see Per project access control for more details.
Enable reviews: Enable review workflow, see Dedicated reviewers.
Enable hooks: Whether unauthenticated Notification hooks are to be used for this repository.
Source language: Language used for source strings in all components. Change this if you are translating from something else than English.

Note

Most of the fields can be edited by project owners or managers, in the Weblate interface.

Adjusting interaction¶

There are also additional features which you can control, like automatic pushing of changes (see also Pushing changes) or maintainership of the Language-Team header.

Component configuration¶

A component is a grouping of something for translation. You enter a VCS repository location and file mask for which files you want translated, and Weblate automatically fetches from this VCS, and finds all matching translatable files.

You can find some examples of typical configurations in the Supported file formats.

Note

It is recommended to keep translation components to a reasonable size - split the translation by anything that makes sense in your case (individual apps or addons, book chapters or websites).

Weblate easily handles translations with 10000s of strings, but it is harder to split work and coordinate among translators with such large translation components.

Should the language definition for a translation be missing, an empty definition is created and named as “cs_CZ (generated)”. You should adjust the definition and report this back to the Weblate authors, so that the missing languages can be included in next release.

The component contains all important parameters for working with the VCS, and for getting translations out of it:

Version control system

VCS to use, see Version control integration for details.

Source code repository

VCS repository used to pull changes, see Accessing repositories for more details.

This can either be a real VCS URL or weblate://project/component indicating that the repository should be shared with another component. See Weblate internal URLs for more details.

Repository push URL

Repository URL used for pushing. This is completely optional and push support is turned off when this is empty. See Accessing repositories for more details on how to specify a repository URL.

Repository browser

URL of repository browser used to display source files (location of used messages). When empty, no such links will be generated. You can use Template markup.

For example on GitHub, use something like https://github.com/WeblateOrg/hello/blob/{{branch}}/{{filename}}#L{{line}}.

Exported repository URL

URL where changes made by Weblate are exported. This is important when Continuous localization is not used, or when there is a need to manually merge changes. You can use Git exporter to automate this for Git repositories.

Repository branch

Which branch to checkout from the VCS, and where to look for translations.

File mask

Mask of files to translate, including path. It should include one “*” replacing language code (see Language definitions for info on how this is processed). In case your repository contains more than one translation file (e.g. more Gettext domains), you need to create a component for each of them.

For example po/*.po or locale/*/LC_MESSAGES/django.po.

In case your filename contains special chars such as [, ], these need to be escaped as [[] or []].

Monolingual base language file

Base file containing string definitions for Monolingual components.

Edit base file

Whether to allow editing the base file for Monolingual components.

Template for new translations

Base file used to generate new translations, e.g. .pot file with Gettext, see Adding new translations for more info.

File format

Translation file format, see also Supported file formats.

Source string bug report address

Email address used for reporting upstream bugs. This address will also receive notification about any source string comments made in Weblate.

Locked

You can lock the translation to prevent updates by users.

Allow translation propagation

You can turn off propagation of translations to this component from other components within same project. This really depends on what you are translating, sometimes it’s desirable to have make use of a translation more than once.

It’s usually a good idea to turn this off for monolingual translations, unless you are using the same IDs across the whole project.

Save translation history

Whether to store a history of translation changes in the database.

Enable suggestions

Whether translation suggestions are accepted for this component.

Suggestion voting

Turns on votecasting for suggestions, see Suggestion voting.

Autoaccept suggestions

Automatically accept voted suggestions, see Suggestion voting.

Translation flags

Customization of quality checks and other Weblate behavior, see Customizing behavior.

Translation license

License of the translation, (does not need to be the same as the source code license).

License URL

URL where users can find the actual text of a license in full.

New translation

How to handle requests for creation of new languages. See Adding new translations.

Language code style

Customize language code used to generate the filename for translations created by Weblate, see Adding new translations for more details.

Merge style

You can configure how updates from the upstream repository are handled. This might not be supported for some VCSs. See Merge or rebase for more details.

Commit message

Message used when committing a translation, see Template markup.

Committer name

Name of the committer used for Weblate commits, the author will always be the real translator. On some VCSs this might be not supported. Default value can be changed by DEFAULT_COMMITER_NAME.

Committer e-mail

Email of committer used for Weblate commits, the author will always be the real translator. On some VCSs this might be not supported. Default value can be changed by DEFAULT_COMMITER_EMAIL.

Push on commit

Whether committed changes should be automatically pushed to the upstream repository. When enabled, the push is initiated once Weblate commits changes to its internal repository (see Lazy commits). To actually enable pushing Repository push URL has to be configured as well.

Age of changes to commit

Sets how old changes (in hours) are to get before they are committed by background task or commit_pending management command. All changes in a component are committed once there is at least one older than this period. The Default value can be changed by COMMIT_PENDING_HOURS.

Language filter

Regular expression used to filter the translation when scanning for file mask. This can be used to limit the list of languages managed by Weblate (e.g. ^(cs|de|es)$ will include only these languages. Please note that you need to list language codes as they appear in the filename.

Note

Most of the fields can be edited by project owners or managers, in the Weblate interface.

Template markup¶

Weblate uses simple markup language in several places where text rendering is needed. It is based on The Django template language, so it can be quite powerful.

Currently it is used in:

Commit message formatting, see Component configuration
Several addons

There following variables are available in the component templates:

{{ language_code }}: Language code
{{ language_name }}: Language name
{{ component_name }}: Component name
{{ component_slug }}: Component slug
{{ project_name }}: Project name
{{ project_slug }}: Project slug
{{ url }}: Translation URL
{{ filename }}: Transaltion filename
{{ stats }}: Translation stats, this has further attributes, examples below.
{{ stats.all }}: Total strings count
{{ stats.fuzzy }}: Count of strings needing review
{{ stats.fuzzy_percent }}: Percent of strings needing review
{{ stats.translated }}: Translated strings count
{{ stats.translated_percent }}: Translated strings percent
{{ stats.allchecks }}: Number of strings with failing checks
{{ stats.allchecks_percent }}: Percent of strings with failing checks
{{ author }}: Author of current commit, available only in the commit scope.
{{ addon_name }}: Name of currently executed addon, available only in the addon commit message.

The following variables are available in the repository browser or editor templates:

{{branch}}: current branch
{{line}}: line in file
{{filename}}: filename, you can also strip leading parts using the parentdir filter, for example {{filename|parentdir}}

You can combine them with filters:

{{ component|title }}

You can use conditions:

{% if stats.translated_percent > 80 %}Well translated!{% endif %}

There is additional tag available for replacing chars:

{% replace component "-" " " %}

You can combine it with filters:

{% replace component|capfirst "-" " " %}

There are also additional filter to manipulate with filenames:

Directory of a file: {{ filename|dirname }}
File without extension: {{ filename|stripext }}
File in parent dir: {{ filename|parentdir }}
It can be used multiple times:  {{ filename|parentdir|parentdir }}

…and other Django template features.

Importing speed¶

Fetching VCS repository and importing translations to Weblate can be a lengthy process, depending on size of your translations. Here are some tips:

Optimize configuration¶

The default configuration is useful for testing and debugging Weblate, while for a production setup, you should do some adjustments. Many of them have quite a big impact on performance. Please check Production setup for more details, especially:

Configure Celery for executing background tasks (see Background tasks using Celery)
Enable caching
Use a powerful database engine
Disable debug mode

Check resource limits¶

If you are importing huge translations or repositories, you might be hit by resource limitations of your server.

Check the amount of free memory, having translation files cached by the operating system will greatly improve performance.
Disk operations might be bottleneck if there is a lot of strings to process - the disk is pushed by both Weblate and the database.
Additional CPU cores might help improve performance of background tasks (see Background tasks using Celery).

Disable unneeded checks¶

Some quality checks can be quite expensive, and if not needed, can save you some time during import if omitted. See CHECK_LIST for more info on how to configure this.

Automatic creation of components¶

In case your project has dozen of translation files (e.g. for different Gettext domains, or parts of Android apps), you might want to import them automatically. This can either be achieved from the command line by using import_project or import_json, or by installing the Component discovery addon.

To use the addon, you first need to create a component for one translation file (choose the one that is the least likely to be renamed or removed in future), and install the addon on this component.

For the management commands, you need to create a project which will contain all components and then run import_project or import_json.

Fulltext search¶

Fulltext search is based on Whoosh. It is processed in the background if Celery is set up. This leads to faster site response, and a less fragmented index with the added cost that it might be slightly outdated.

Language definitions¶

To properly present different translations, Weblate needs some info about languages used. Currently definitions for about 350 languages are included, and the definition includes language name, text direction, plural definitions and language code.

Parsing language codes¶

While parsing translations, Weblate attempts to map language code (usually the ISO 639-1 one) to any existing language object. If no exact match can be found, an attempt will be made to best fit into an existing language (e.g. ignoring default country code for a given language - choosing cs instead of cs_CZ). Should also fail, a new language definition will be created using the defaults (left to right text direction, one plural) and naming of the language :guilabel:xx_XX (generated). You might want to change this in the admin interface (see Changing language definitions) and report it to the issue tracker (see Contributing).

Changing language definitions¶

You can change language definitions in the admin interface (see Django admin interface). The Weblate languages section allows changing or adding language definitions. While editing, make sure all fields are correct (especially plurals and text direction), otherwise translators be unable to properly edit those translations.

Continuous localization¶

There is infrastructure in place so that your translation closely follows development. This way translators can work on translations the entire time, instead of working through huge amount of new text just prior to release.

This is the process:

Developers make changes and push them to the VCS repository.
Optionally the translation files are updated (this depends on the file format, see Why does Weblate still show old translation strings when I’ve updated the template?).
Weblate pulls changes from the VCS repository, see Updating repositories.
Once Weblate detects changes in translations, translators are notified based on their subscription settings.
Translators submit translations using the Weblate web interface, or upload offline changes.
Once the translators are finished, Weblate commits the changes to the local repository (see Lazy commits) and pushes them back if it has permissions to do so (see Pushing changes).

Updating repositories¶

You should set up some way of updating backend repositories from their source.

Use Notification hooks to integrate with most of common code hosting services
Manually trigger update either in the repository management or using Weblate’s Web API or Weblate Client
Enable AUTO_UPDATE to automatically update all components on your Weblate instance
Exectute updategit (with selection of project or –all to update all)

Whenever Weblate updates the repository, the post update addons will be triggered, see Addons.

Avoiding merge conflicts¶

To avoid merge conflicts, control when translation files are updated in the upstream repository to avoid Weblate having changes on the same file.

You can achieve this using Weblate’s Web API to force Weblate to push all pending changes and lock the translation while you are doing changes on your side.

The script for doing updates can look like this:

# Lock Weblate translation
wlc lock
# Push changes from Weblate to upstream repository
wlc push
# Pull changes from upstream repository to your local copy
git pull
# Update translation files, this example is for Django
./manage.py makemessages --keep-pot -a
git commit -m 'Locale updates' -- locale
# Push changes to upstream repository
git push
# Tell Weblate to pull changes (not needed if Weblate follows your repo
# automatically)
wlc pull
# Unlock translations
wlc unlock

If you have multiple components sharing same repository, you need to lock them all separately:

wlc lock foo/bar
wlc lock foo/baz
wlc lock foo/baj

Note

The example uses Weblate Client, which needs configuration (API keys) to be able to control Weblate remotely. You can also achieve this using any HTTP client instead of wlc, e.g. curl, see Weblate’s Web API.

Automatically receiving changes from GitHub¶

Weblate comes with native support for GitHub.

If you are using Hosted Weblate, the recommended approach is to install the Hosted Weblate app, that way you will get the correct setup without having to set much up. It can also be used for pushing changes back.

To receive notifications on every push to a GitHub repository, add the Weblate Webhook in the repository settings (Webhooks) as shown on the image below:

For the payload URL, append /hooks/github/ to your Weblate URL, for example for the Hosted Weblate service, this is https://hosted.weblate.org/hooks/github/.

You can leave other values at default settings (Weblate can handle both content types and consumes just the push event).

Automatically receiving changes from Bitbucket¶

Weblate has support for Bitbucket webhooks, add a webhook which triggers upon repository push, with destination to /hooks/bitbucket/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/bitbucket/).

Automatically receiving changes from GitLab¶

Weblate has support for GitLab hooks, add a project webhook with destination to /hooks/gitlab/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/gitlab/).

Automatically receiving changes from Pagure¶

New in version 3.3.

Weblate has support for Pagure hooks, add a webhook with destination to /hooks/pagure/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/pagure/). This can be done in Activate Web-hooks under Project options:

Automatically receiving changes from Azure Repos¶

New in version 3.8.

Weblate has support for Azure Repos web hooks, add a webhook for Code pushed event with destination to /hooks/azure/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/azure/). This can be done in Service hooks under Project settings.

Automatically updating repositories nightly¶

Weblate automatically fetches remote repositories nightly to improve performance when merging changes later. You can optionally turn this into doing nightly merges as well, by enabling AUTO_UPDATE.

Pushing changes¶

Each translation component can have a push URL set up (see Component configuration), and in that case Weblate will be able to push change to the remote repository. Weblate can be also be configured to automatically push changes on every commit (this is default, see Component configuration). If you do not want changes to be pushed automatically, you can do that manually under Repository maintenance or using API via wlc push.

If you are using SSH to push, you will need to have a key without a passphrase (or use ssh-agent for Django), and the remote server needs to be verified by you via the admin interface first, otherwise pushing will fail.

The push options differ based on the Version control integration used, more details are found in that chapter.

Note

You can also enable automatic pushing of changes on commits, this can be done in Component configuration.

See also

See Accessing repositories for setting up SSH keys, and Lazy commits for info about when Weblate decides to commit changes.

Pushing changes from Hosted Weblate¶

For Hosted Weblate there is a dedicated push user registered on GitHub, Bitbucket and GitLab (with username weblate named Weblate push user). You need to add this user as a collaborator and give it permission to push to your repository.

The user is added to the repository (in some cases this happens immediately, on GitHub it typically happens after accepting invitations what happens automatically every hour), you can configure your component push URL to a ssh URL of your repository (see Component configuration) and enjoy Weblate automatically pushing changes to your repository.

In case you do not want direct pushes by Weblate, there is support for GitHub pull requests or Gerrit reviews, you can activate these by choosing GitHub or Gerrit as VCS in Component configuration.

Protected branches¶

If you are using Weblate on protected branch, you can configure it to use pull requests and perform actual review on the translations (what might be problematic for languages you do not know). Alternative approach is to to waive this limitation for the Weblate push user.

For example on GitHub this can be done in the repository configuration:

Merge or rebase¶

By default, Weblate merges the upstream repository into its own. This is the safest way in case you also access the underlying repository by other means. In case you don’t need this, you can enable rebasing of changes on upstream, which will produce history with fewer merge commits.

Note

Rebasing can cause you trouble in case of complicated merges, so carefully consider whether or not you want to enable them.

Interacting with others¶

Weblate makes it easy to interact with others using its API.

See also

Weblate’s Web API

Lazy commits¶

The behaviour of Weblate is to group commits from the same author into one commit if possible. This greatly reduces the number of commits, however you might need to explicitly tell it to do the commits in case you want to get the VCS repository in sync, e.g. for merge (this is by default allowed for the Managers group, see Access control).

The changes in this mode are committed once any of the following conditions are fulfilled:

Somebody else changes an already changed string.
A merge from upstream occurs.
An explicit commit is requested.
Change is older than period defined as Age of changes to commit on Component configuration.

If you want to commit changes more frequently and without checking of age, you can schedule a regular task to perform a commit:

CELERY_BEAT_SCHEDULE = {
    # Unconditionally commit all changes every 2 minutes
    "commit": {
        "task": "weblate.trans.tasks.commit_pending",
        # Ommiting hours will honor per component settings,
        # otherwise components with no changes older than this
        # won't be committed
        "kwargs": {"hours": 0},
        # How frequently to execute the job in seconds
        "schedule": 120,
    }
}

Processing repository with scripts¶

The way to customize how Weblate interacts with the repository is Addons. Consult Executing scripts from addon for info on how to execute external scripts through addons.

Licensing translations¶

Weblate allows you to specify under which license the translations are contributed. This is especially important to specify if the translations are open to the public to raise proper expectations what can be done with the translations.

There are two things you specify on the Component configuration - license information and the contributor agreement.

License information¶

Upon specifying license information (license name and URL), this information is shown in the translation information, but it is not enforced in any way.

Usually this is best location to place information on licensing where no explicit consent is required.

Contributor agreement¶

Once you specify contributor agreement, only users who have agreed to it will be able to contribute. This is clearly visible when accessing the translation:

The entered text is formatted into paragraphs and external links are possible. HTML markup can not be used.

Signed off by¶

Should your project require Signed-off-by header in the commits, you should enable contributor agreement with the DCO text and add the header to the commit message (see Template markup for more details). The full commit message can look like:

Translated using Weblate ({{ language_name }})

Currently translated at {{ stats.translated_percent }}% ({{ stats.translated }} of {{ stats.all }} strings)

Translation: {{ project_name }}/{{ component_name }}
Translate-URL: {{ url }}
Signed-off-by: {{ author }}

User licenses¶

User can review licenses on projects he is contributing to in the profile:

Translation process¶

Suggestion voting¶

New in version 1.6: This feature is available since Weblate 1.6.

By default, everyone can add suggestions, which logged in users can accept. Requiring more then one person for acceptance can be achieved by suggestion voting. You can enable this on Component configuration configuration by Suggestion voting and Autoaccept suggestions. The first one enables the voting feature, while the latter sets the threshold a suggestion is automatically is accepted (this includes a vote from the user making the suggestion).

Note

Once automatic acceptance is set up, normal users lose the privilege to directly save translations or accept suggestions. This can be overridden by Can override suggestion state privilege (see Access control).

You can combine these with Access control into one of the following setups:

Users suggest and vote for suggestions, a limited group controls what is accepted - turn on voting, but automatic acceptance off, and don’t let users save translations.
Users suggest and vote for suggestions with automatical acceptance once the defined number of them agree - turn on voting and set the desired number of votes for automatic acceptance.
Optional voting for suggestions - you can also turn on voting only, and in this case it can optionally be used by users when they are unsure about a translation by making multiple suggestions.

Additional info on source strings¶

Enhance the translation process with info available in the translation files. This includes string prioritization, check flags, or providing visual context. All these features can be set on the Reviewing source strings:

Access this directly from the translating interface by clicking the “Edit” icon next to Screenshot context or Flags.

Strings prioritization¶

New in version 2.0.

You can change string priority, strings with higher priority are offered first for translation. This can be useful for prioritizing translation of strings which are seen first by users or are otherwise important. This can be achieved using priority flag.

See also

Quality checks

Translation flags¶

New in version 2.4.

Changed in version 3.3: Previously this was called Quality checks flags, but as it no longer configures only checks, the name was changed to be more generic.

The default set of translation flags is determined by the translation Component configuration and the translation file. However, you might want to use it to customize this per source string.

See also

Quality checks

Visual context for strings¶

New in version 2.9.

You can upload a screenshot showing a given source string in use within your program. This helps translators understand where it is used, and how it should be translated.

The uploaded screenshot is shown in the translation context sidebar:

In addition to Reviewing source strings, screenshots have a separate management interface under Tools menu. Upload screenshots, assign them to source strings manually or with the use of OCR.

Once a screenshot is uploaded, this interface handles management and assigning it to source strings:

Checks and fixups¶

Custom automatic fixups¶

You can also implement your own automatic fixup in addition to the standard ones and include them in AUTOFIX_LIST.

The automatic fixes are powerful, but can also cause damage; be careful when writing one.

For example, the following automatic fixup would replace every occurrence of string foo in translation with bar:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#

from django.utils.translation import ugettext_lazy as _

from weblate.trans.autofixes.base import AutoFix


class ReplaceFooWithBar(AutoFix):
    """Replace foo with bar."""

    name = _("Foobar")

    def fix_single_target(self, target, source, unit):
        if "foo" in target:
            return target.replace("foo", "bar"), True
        return target, False

To install custom checks, you need to provide a fully-qualified path to the Python class in the AUTOFIX_LIST, see Custom quality checks and auto fixes.

Customizing behavior¶

You can fine tune Weblate behavior (mostly checks) for each source string (in source strings review, see Additional info on source strings) or in the Component configuration (Translation flags). Some file formats also allow to specify flags directly in the format.

Here is a list of flags currently accepted:

rst-text: Treat text as RST document, effects Unchanged translation.
md-text: Treat text as Markdown document.
dos-eol: Use DOS end of line markers instead of Unix ones (\r\n instead of \n).
url: The string should consist of URL only.
priority:N: Priority of the string. Higher priority strings are presented first to translate. The default priority is 100, the higher priority string has, the earlier is offered to translate.
max-length:N: Limit maximal length for string to N chars, see Maximum Length
xml-text: Treat text as XML document, affects Invalid XML markup and XML tags mismatch.
font-family:NAME: Define font family for rendering checks, see Managing fonts.
font-weight:WEIGHT: Define font weight for rendering checks, see Managing fonts.
font-size:SIZE: Define font size for rendering checks, see Managing fonts.
font-spacing:SPACING: Define font spacing for rendering checks, see Managing fonts.
python-format, c-format, php-format, python-brace-format, javascript-format, c-sharp-format, java-format, java-messageformat, auto-java-messageformat, qt-format, qt-plural-format, ruby-format: Treats all strings like format strings, affects Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Formatted strings, Unchanged translation.
ignore-end-space: Skip the “Trailing space” quality check.
ignore-inconsistent: Skip the “Inconsistent” quality check.
ignore-translated: Skip the “Has been translated” quality check.
ignore-begin-newline: Skip the “Starting newline” quality check.
ignore-zero-width-space: Skip the “Zero-width space” quality check.
ignore-escaped-newline: Skip the “Mismatched n” quality check.
ignore-same: Skip the “Unchanged translation” quality check.
ignore-end-question: Skip the “Trailing question” quality check.
ignore-end-ellipsis: Skip the “Trailing ellipsis” quality check.
ignore-ellipsis: Skip the “Ellipsis” quality check.
ignore-python-brace-format: Skip the “Python brace format” quality check.
ignore-end-newline: Skip the “Trailing newline” quality check.
ignore-c-format: Skip the “C format” quality check.
ignore-javascript-format: Skip the “JavaScript format” quality check.
ignore-optional-plural: Skip the “Optional plural” quality check.
ignore-end-exclamation: Skip the “Trailing exclamation” quality check.
ignore-end-colon: Skip the “Trailing colon” quality check.
ignore-xml-invalid: Skip the “Invalid XML markup” quality check.
ignore-xml-tags: Skip the “XML tags mismatch” quality check.
ignore-python-format: Skip the “Python format” quality check.
ignore-plurals: Skip the “Missing plurals” quality check.
ignore-begin-space: Skip the “Starting spaces” quality check.
ignore-bbcode: Skip the “Mismatched BBcode” quality check.
ignore-multiple-failures: Skip the “Multiple failing checks” quality check.
ignore-php-format: Skip the “PHP format” quality check.
ignore-end-stop: Skip the “Trailing stop” quality check.
ignore-angularjs-format: Skip the “AngularJS interpolation string” quality check.
ignore-c-sharp-format: Skip the “C# format” quality check.
ignore-java-format: Skip the “Java format” quality check.
ignore-qt-format: Skip the “Qt format” quality check.
ignore-qt-plural-format: Skip the “Qt plural format” quality check.
ignore-ruby-format: Skip the “Ruby format” quality check.

Note

Generally the rule is named ignore-* for any check, using its identifier, so you can use this even for your custom checks.

These flags are understood both in Component configuration settings, per source string settings and in translation file itself (eg. in GNU Gettext).

Managing fonts¶

New in version 3.7.

The Maximum size of translation check needs fonts to properly calculate dimensions of rendered text. The fonts can be managed in Weblate in the font management tool which you can find as Fonts under Tools menu of your translation project.

You can upload TrueType or OpenType fonts, configure font groups and use those in the the check.

The font groups allow you to define different fonts for different languages, what is typically needed for non latin languages:

The font groups are identified by name, which can not contain whitespace or special chars to be easy to use in check definition:

After upload the font family and style is automatically recognized:

You can have number of fonts loaded into Weblate:

Writing own checks¶

Weblate comes with wide range of quality checks (see Quality checks), though they might not 100% cover all you want to check. The list of performed checks can be adjusted using CHECK_LIST and you can also add custom checks. All you need to do is to subclass weblate.checks.Check, set few attributes and implement either check or check_single methods (first one if you want to deal with plurals in your code, the latter one does this for you). You will find below some examples.

To install custom checks, you need to provide a fully-qualified path to the Python class in the CHECK_LIST, see Custom quality checks and auto fixes.

Checking translation text does not contain “foo”¶

This is a pretty simple check which just checks whether translation does not contain string “foo”.

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Simple quality check example."""

from django.utils.translation import ugettext_lazy as _

from weblate.checks.base import TargetCheck


class FooCheck(TargetCheck):

    # Used as identifier for check, should be unique
    # Has to be shorter than 50 chars
    check_id = "foo"

    # Short name used to display failing check
    name = _("Foo check")

    # Description for failing check
    description = _("Your translation is foo")

    # Real check code
    def check_single(self, source, target, unit):
        return "foo" in target

Checking Czech translation text plurals differ¶

Check using language information to verify that two plural forms in Czech language are not same.

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Quality check example for Czech plurals."""

from django.utils.translation import ugettext_lazy as _

from weblate.checks.base import TargetCheck


class PluralCzechCheck(TargetCheck):

    # Used as identifier for check, should be unique
    # Has to be shorter than 50 chars
    check_id = "foo"

    # Short name used to display failing check
    name = _("Foo check")

    # Description for failing check
    description = _("Your translation is foo")

    # Real check code
    def check_target_unit(self, sources, targets, unit):
        if self.is_language(unit, ("cs",)):
            return targets[1] == targets[2]
        return False

    def check_single(self, source, target, unit):
        """We don't check target strings here."""
        return False

Machine translation¶

Weblate has built in support for several machine translation services and it’s up to the administrator to enable them. The services have different terms of use, so please check whether you are allowed to use them before enabling them in Weblate. The individual services are enabled using MT_SERVICES.

The source language can be configured at Project configuration.

Amagama¶

Special installation of tmserver run by Virtaal authors.

To enable this service, add weblate.machinery.tmserver.AmagamaTranslation to MT_SERVICES.

See also

Amagama, Amagama Translation Memory

Apertium¶

A free/open-source machine translation platform providing translation to a limited set of languages.

The recommended way to use Apertium is to run your own Apertium APy server.

To enable this service, add weblate.machinery.apertium.ApertiumAPYTranslation to MT_SERVICES and set MT_APERTIUM_APY.

AWS¶

New in version 3.1.

Amazon Translate is a neural machine translation service for translating text to and from English across a breadth of supported languages.

To enable this service, add weblate.machinery.aws.AWSTranslation to MT_SERVICES, install the boto3 module and set the settings.

Baidu API machine translation¶

New in version 3.2.

Machine translation service provided by Baidu.

This service uses an API and you need to obtain ID and API key from Baidu.

To enable this service, add weblate.machinery.baidu.BaiduTranslation to MT_SERVICES and set MT_BAIDU_ID and MT_BAIDU_SECRET.

DeepL¶

New in version 2.20.

DeepL is paid service providing good machine translation for few languages. According to some benchmark it’s currently best available service.

To enable this service, add weblate.machinery.deepl.DeepLTranslation to MT_SERVICES and set MT_DEEPL_KEY.

Glosbe¶

Free dictionary and translation memory for almost every living language.

API is free to use, but subject to the used data source license. There is a limit of calls that may be done from one IP in fixed period of time, to prevent abuse.

To enable this service, add weblate.machinery.glosbe.GlosbeTranslation to MT_SERVICES.

See also

Glosbe website

Google Translate¶

Machine translation service provided by Google.

This service uses Translation API and you need to obtain an API key and enable billing on Google API console.

To enable this service, add weblate.machinery.google.GoogleTranslation to MT_SERVICES and set MT_GOOGLE_KEY.

Microsoft Cognitive Services Translator¶

New in version 2.10.

Machine translation service provided by Microsoft in Azure portal as a one of Cognitive Services.

You need to register at Azure portal and use the key you obtain there.

To enable this service, add weblate.machinery.microsoft.MicrosoftCognitiveTranslation to MT_SERVICES and set MT_MICROSOFT_COGNITIVE_KEY.

Microsoft Terminology Service¶

New in version 2.19.

The Microsoft Terminology Service API allows you to programmatically access the terminology, definitions and user interface (UI) strings available on the Language Portal through a web service.

To enable this service, add weblate.machinery.microsoftterminology.MicrosoftTerminologyService to MT_SERVICES.

See also

Microsoft Terminology Service API

MyMemory¶

Huge translation memory with machine translation.

Free, anonymous usage is currently limited to 100 requests/day, or to 1000 requests/day when you provide contact e-mail in MT_MYMEMORY_EMAIL. You can also ask them for more.

To enable this service, add weblate.machinery.mymemory.MyMemoryTranslation to MT_SERVICES and set MT_MYMEMORY_EMAIL.

Netease Sight API machine translation¶

New in version 3.3.

Machine translation service provided by Netease.

This service uses an API and you need to obtain key and secret from Netease.

To enable this service, add weblate.machinery.youdao.NeteaseSightTranslation to MT_SERVICES and set MT_NETEASE_KEY and MT_NETEASE_SECRET.

tmserver¶

You can run your own translation memory server which is bundled with Translate-toolkit and let Weblate talk to it. You can also use it with amaGama server, which is an enhanced version of tmserver.

First you will want to import some data to the translation memory:

To enable this service, add weblate.machinery.tmserver.TMServerTranslation to MT_SERVICES.

build_tmdb -d /var/lib/tm/db -s en -t cs locale/cs/LC_MESSAGES/django.po
build_tmdb -d /var/lib/tm/db -s en -t de locale/de/LC_MESSAGES/django.po
build_tmdb -d /var/lib/tm/db -s en -t fr locale/fr/LC_MESSAGES/django.po

Now you can start tmserver to listen to your requests:

tmserver -d /var/lib/tm/db

And configure Weblate to talk to it:

MT_TMSERVER = 'http://localhost:8888/tmserver/'

Yandex Translate¶

Machine translation service provided by Yandex.

This service uses Translation API and you need to obtain API key from Yandex.

To enable this service, add weblate.machinery.yandex.YandexTranslation to MT_SERVICES and set MT_YANDEX_KEY.

Youdao Zhiyun API machine translation¶

New in version 3.2.

Machine translation service provided by Youdao.

This service uses an API and you need to obtain ID and API key from Youdao.

To enable this service, add weblate.machinery.youdao.YoudaoTranslation to MT_SERVICES and set MT_YOUDAO_ID and MT_YOUDAO_SECRET.

Weblate¶

Weblate can be source of machine translation as well. It is based on the fulltext engine Whoosh and provides both exact and inexact matches.

To enable these services, add weblate.machinery.weblatetm.WeblateTranslation to MT_SERVICES.

Weblate Translation Memory¶

New in version 2.20.

The Translation Memory can be used as source for machine translation suggestions as well.

To enable these services, add weblate.memory.machine.WeblateMemory to the MT_SERVICES. This service is enabled by default.

SAP Translation Hub¶

Machine translation service provided by SAP.

You need to have a SAP account (and enabled the SAP Translation Hub in the SAP Cloud Platform) to use this service.

To enable this service, add weblate.machinery.saptranslationhub.SAPTranslationHub to MT_SERVICES and set appropriate access to either sandbox or productive API.

Note

To access the Sandbox API, you need to set MT_SAP_BASE_URL and MT_SAP_SANDBOX_APIKEY.

To access the productive API, you need to set MT_SAP_BASE_URL, MT_SAP_USERNAME and MT_SAP_PASSWORD.

Custom machine translation¶

You can also implement your own machine translation services using a few lines of Python code. This example implements translation to a fixed list of languages using dictionary Python module:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Machine translation example."""

import dictionary
from weblate.machinery.base import MachineTranslation


class SampleTranslation(MachineTranslation):
    """Sample machine translation interface."""

    name = "Sample"

    def download_languages(self):
        """Return list of languages your machine translation supports."""
        return {"cs"}

    def download_translations(self, source, language, text, unit, user):
        """Return tuple with translations."""
        return [
            {'text': t, 'quality': 100, 'service': self.name, 'source': text}
            for t in dictionary.translate(text)
        ]

You can list own class in MT_SERVICES and Weblate will start using that.

Addons¶

New in version 2.19.

Addons provide ways to customize translation workflow. You can install addons to your translation component and they will work behind the scenes. The addon management can be found under Manage menu of a translation component.

Built in addons¶

Cleanup translation files¶

Update all translation files to match the monolingual base file. For most file formats, this means removing stale translation keys no longer present in the base file.

Language consistency¶

This addon ensures that all components within one project have translation to same languages.

Unlike most others, this addon operates on whole project.

Component discovery¶

This addon automatically adds or removes components to the project based on file changes in the version control system.

It is similar to the import_project management command, but the major difference is that it is triggered on every VCS update. This way you can easily track multiple translation components within one VCS.

To use component discovery, you first need to create one component which will act as master and others will use Weblate internal URLs to it as a VCS configuration. You should choose the one which is less likely to disappear in the future here.

Once you have one component from the target VCS, you can configure the discovery addon to find all translation components in the VCS. The matching is done using regular expression so it can be quite powerful, but it can be complex to configure. You can use examples in the addon help for some common use cases.

Once you hit save, you will be presented with a preview of matched components, so you can check whether the configuration actually matches your needs:

See also

Template markup

Flag unchanged translations as “Needs editing”¶

New in version 3.1.

Whenever a new translatable string is imported from the VCS and it matches source strings, it is flagged as needing editing in Weblate. This is especially useful for file formats that include all strings even if they are not translated.

Flag new source strings as “Needs editing”¶

Whenever a new source string is imported from the VCS, it is flagged as needing editing in Weblate. This way you can easily filter and edit source strings written by the developers.

Flag new translations as “Needs editing”¶

Whenever a new translatable string is imported from the VCS, it is flagged as needing editing in Weblate. This way you can easily filter and edit translations created by the developers.

Statistics generator¶

This addon generates a file containing detailed information about the translation. You can use Django template in both filename and content, see Template markup for detailed markup description.

For example generating summary file for each translations:

Name of generated file

locale/{{ language_code }}.json

Content

{
   "language": "{{ language_code }}",
   "strings": "{{ stats.all }}",
   "translated": "{{ stats.translated }}",
   "last_changed": "{{ stats.last_changed }}",
   "last_author": "{{ stats.last_author }}",
}

See also

Template markup

Contributors in comment¶

Update comment in the PO file header to include contributor name and years of contributions.

Update ALL_LINGUAS variable in the “configure” file¶

Updates the ALL_LINGUAS variable in configure, configure.in or configure.ac files, when a new translation is added.

Customize gettext output¶

Allows customization of gettext output behavior, for example line wrapping.

Update LINGUAS file¶

Updates the LINGUAS file when a new translation is added.

Generate MO files¶

Automatically generates MO file for every changed PO file.

Update PO files to match POT (msgmerge)¶

Update all PO files to match the POT file using msgmerge. This is triggered whenever new changes are pulled from the upstream repository.

Squash Git commits¶

Squash Git commits prior to pushing changes.

Customize JSON output¶

Allows to customize JSON output behavior, for example indentation or sorting.

Formats the Java properties file¶

This addon sorts the Java properties file.

Stale comment removal¶

New in version 3.7.

Set timeframe for removal of comments. This can be useful to remove old comments which might have become outdated. Use with care as comment being old does not mean it has lost it’s importation.

Stale suggestion removal¶

New in version 3.7.

Set timeframe for removal of suggestions. This can be very useful in connection with suggestion voting (see Peer review) to remove suggestions which don’t receive enough positive votes until certain deadline.

Customizing list of addons¶

List of addons is configured by WEBLATE_ADDONS, to add another addon simply include class absolute name in this setting.

Writing addon¶

You can write own addons as well, all you need to do is subclass BaseAddon, define addon metadata and implement callback which will do the processing.

You can look at example addon for more information:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#

from __future__ import unicode_literals

from django.utils.translation import ugettext_lazy as _

from weblate.addons.base import BaseAddon
from weblate.addons.events import EVENT_PRE_COMMIT


class ExampleAddon(BaseAddon):
    # Filter for compatible components, every key is
    # matched against property of component
    compat = {
        'file_format': frozenset((
            'po', 'po-mono',
        )),
    }
    # List of events addon should receive
    events = (EVENT_PRE_COMMIT,)
    # Addon unique identifier
    name = 'weblate.example.example'
    # Verbose name shown in the user interface
    verbose = _('Example addon')
    # Detailed addon description
    description = _('This addon does nothing it is just an example.')

    # Callback to implement custom behavior
    def pre_commit(self, translation, author):
        return

Executing scripts from addon¶

You can also use addons to execute external scripts. This used to be integrated in Weblate, but now you have to write little code to wrap your script with an addon.

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""
Example pre commit script
"""

from __future__ import unicode_literals

from django.utils.translation import ugettext_lazy as _

from weblate.addons.events import EVENT_PRE_COMMIT
from weblate.addons.scripts import BaseScriptAddon


class ExamplePreAddon(BaseScriptAddon):
    # Event used to trigger the script
    events = (EVENT_PRE_COMMIT,)
    # Name of the addon, has to be unique
    name = 'weblate.example.pre'
    # Verbose name and long descrption
    verbose = _('Execute script before commit')
    description = _('This addon executes a script.')

    # Script to execute
    script = '/bin/true'
    # File to add in commit (for pre commit event)
    # does not have to be set
    add_file = 'po/{{ language_code }}.po'

For installing instructions see Custom addons.

The script is executed with the current directory set to the root of the VCS repository for given component.

Additionally, the following environment variables are available:

WL_VCS¶: Version control system used.

WL_REPO¶: Upstream repository URL.

WL_PATH¶: Absolute path to VCS repository.

WL_BRANCH¶: New in version 2.11.

Repository branch configured in the current component.

WL_FILEMASK¶: File mask for current component.

WL_TEMPLATE¶: File name of template for monolingual translations (can be empty).

WL_NEW_BASE¶: New in version 2.14.

File name of the file which is used for creating new translations (can be empty).

WL_FILE_FORMAT¶: File format used in current component.

WL_LANGUAGE¶: Language of currently processed translation (not available for component level hooks).

WL_PREVIOUS_HEAD¶: Previous HEAD on update (available only available when running post update hook).

See also

Component configuration

Post update repository processing¶

Post update repository processing can be used to update translation files on the source change. To achieve this, please remember that Weblate only sees files which are committed to the VCS, so you need to commit changes as a part of the script.

For example with gulp you can do it using following code:

#! /bin/sh
gulp --gulpfile gulp-i18n-extract.js
git commit -m 'Update source strings' src/languages/en.lang.json

Pre commit processing of translations¶

In many cases you might want to automatically do some changes to the translation before it is committed to the repository. The pre commit script is exactly the place to achieve this.

It is passed a single parameter consisting of filename of current translation.

Translation Memory¶

New in version 2.20.

Weblate comes with a built-in translation memory.

The translation memory consists of following content:

Manually imported translation memory (see User interface).
Automatically stored translations performed in Weblate (depending on Translation memory scopes).

The translation memory can be used to get matches:

In the Machine translation view while translating.
Automatically translate strings using Automatic translation.

For installation tips, see Weblate Translation Memory, however this service is enabled by default.

Translation memory scopes¶

New in version 3.2: The different translation memory scopes are available since Weblate 3.2, prior to this release translation memory could be only loaded from file corresponding to the current imported translation memory scope.

The translation memory scopes are there to allow both privacy and sharing of translations, depending on the actual desired behavior.

Imported translation memory¶

You can import arbitrary translation memory data using import_memory command. The memory content will be available for all users and projects.

Per user translation memory¶

All user translations are automatically stored in personal translation memory. This memory is available only for this user.

Per project translation memory¶

All translations within a project are automatically stored in a project translation memory. This memory is available only for this project.

Shared translation memory¶

All translation within projects which have enabled shared translation memory are stored in shared translation memory. This shared memory is available for all projects then.

Please consider carefully when enabling this feature on shared Weblate installations as this might have severe implications:

The translations can be used by anybody else.
This might lead to disclosing secret information.

Managing translation memory¶

User interface¶

New in version 3.2.

There is basic user interface to manage per user and per project translation memories. It can be used to download, wipe or import it.

The downloads in JSON are useful for Weblate, TMX is provided for interoperability with other tools.

Management interface¶

There are several management commands to manipulate with the translation memory content, these operate on memory as whole not filtered by scopes (unless requested by parameters):

dump_memory: Exporting the memory into JSON
import_memory: Importing TMX or JSON files into the memory
list_memory: Listing memory content
delete_memory: Deleting content from the memory

Configuration¶

All settings are stored in settings.py (as usual for Django).

Note

After changing any of these settings, you need to restart Weblate. In case it is run as mod_wsgi, you need to restart Apache to reload the configuration.

See also

Please also check Django’s documentation for parameters which configure Django itself.

AKISMET_API_KEY¶

Weblate can use Akismet to check incoming anonymous suggestions for spam. Visit akismet.com to purchase an API key and associate it with a site.

ANONYMOUS_USER_NAME¶

User name of user for defining privileges of not logged in user.

See also

Access control

AUDITLOG_EXPIRY¶

New in version 3.6.

How long (in days) Weblate should keep audit log containing information about account activity.

Defaults to 180 days.

AUTH_LOCK_ATTEMPTS¶

New in version 2.14.

Maximum number of failed authentication attempts before rate limiting is applied.

This is currently applied in the following locations:

On login, the account password is reset. User will not be able to log in after that using password until he asks for password reset.
On password reset, the reset mails are no longer sent. This avoids spamming user with too many password reset attempts.

Defaults to 10.

See also

Rate limiting,

AUTO_UPDATE¶

New in version 3.2.

Automatically update all repositories on daily basis. This can be useful if you do not use Notification hooks to update Weblate repositories automatically.

Note

This requires Background tasks using Celery working and you will have to restart celery for this setting to take effect.

AVATAR_URL_PREFIX¶

Prefix for constructing avatar URLs. The URL will be constructed like: ${AVATAR_URL_PREFIX}/avatar/${MAIL_HASH}?${PARAMS}. Following services are known to work:

Gravatar (default), see https://gravatar.com/: AVATAR_URL_PREFIX = 'https://www.gravatar.com/'
Libravatar, see https://www.libravatar.org/: AVATAR_URL_PREFIX = 'https://seccdn.libravatar.org/'

RATELIMIT_ATTEMPTS¶

New in version 3.2.

Maximum number of authentication attempts before rate limiting applies.

Defaults to 5.

RATELIMIT_WINDOW¶

New in version 3.2.

Length of authentication window for rate limiting in seconds.

Defaults to 300 (5 minutes).

RATELIMIT_LOCKOUT¶

New in version 3.2.

Length of authentication lockout window after rate limit is applied.

Defaults to 600 (10 minutes).

AUTH_TOKEN_VALID¶

New in version 2.14.

Validity of token in activation and password reset mails in seconds.

Defaults to 3600 (1 hour).

AUTH_PASSWORD_DAYS¶

New in version 2.15.

Define (in days) how long in past Weblate should reject reusing same password.

Note

Password changes done prior to Weblate 2.15 will not be accounted for this policy, it is valid only

Defaults to 180 days.

AUTOFIX_LIST¶

List of automatic fixups to apply when saving the message.

You need to provide a fully-qualified path to the Python class implementing the autofixer interface.

Available fixes:

weblate.trans.autofixes.whitespace.SameBookendingWhitespace: Fixes up whitespace in beginning and end of the string to match source.
weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis: Replaces trailing dots with ellipsis if source string has it.
weblate.trans.autofixes.chars.RemoveZeroSpace: Removes zero width space char if source does not contain it.
weblate.trans.autofixes.chars.RemoveControlCharS: Removes control characters if source does not contain it.

For example you can enable only few of them:

AUTOFIX_LIST = (
    'weblate.trans.autofixes.whitespace.SameBookendingWhitespace',
    'weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis',
)

BASE_DIR¶

Base directory where Weblate sources are located. This is used to derive several other paths by default:

DATA_DIR

Default value: Top level directory of Weblate sources.

CHECK_LIST¶

List of quality checks to perform on translation.

You need to provide a fully-qualified path to the Python class implementing the check interface.

Some of the checks are not useful for all projects, so you are welcome to adjust the list list of checks to be performed on your installation.

By default all built in quality checks (see Quality checks) are enabled, you can use this setting to change this. Also the Sample configuration comes with this setting commented out to use default value. This enables you to get new checks automatically enabled on upgrade.

You can disable all checks:

CHECK_LIST = ()

You can enable only few of them:

CHECK_LIST = (
    'weblate.checks.chars.BeginNewlineCheck',
    'weblate.checks.chars.EndNewlineCheck',
    'weblate.checks.chars.MaxLengthCheck',
)

Note

Once you change this setting the existing checks will still be stored in the database, only newly changed translations will be affected by the change. To apply the change to the stored translations, you need to run updatechecks.

See also

Quality checks, Customizing behavior

COMMENT_CLEANUP_DAYS¶

New in version 3.6.

Automatically delete comments after given number of days. Defaults to None what means no deletion at all.

COMMIT_PENDING_HOURS¶

New in version 2.10.

Default interval for committing pending changes using commit_pending.

DATA_DIR¶

Directory where Weblate stores all data. This consists of VCS repositories, fulltext index and various configuration files for external tools.

The following subdirectories usually exist:

home: Home directory used for invoking scripts.
ssh: SSH keys and configuration.
static: Default location for Django static files, specified by STATIC_ROOT.
media: Default location for Django media files, specified by MEDIA_ROOT.
memory: Translation memory data using Whoosh engine (see Translation Memory).
vcs: Version control repositories.
whoosh: Fulltext search index using Whoosh engine.
backups: Dump of data in daily backups, see Dumped data for backups.

Note

This directory has to be writable by Weblate. If you are running Weblate as uwsgi this means that it should be writable by the www-data user.

The easiest way to achieve is to make the user own the directory:

sudo chown www-data:www-data -R $DATA_DIR

Defaults to $BASE_DIR/data.

DEFAULT_ACCESS_CONTROL¶

New in version 3.3.

Choose default access control when creating new project, possible values are currently:

0: Public
1: Protected
100: Private
200: Custom

Use Custom if you are going to manage ACL manually and do not want to rely on Weblate internal management.

DEFAULT_COMMITER_EMAIL¶

New in version 2.4.

Default committer e-mail when creating translation component (see Component configuration), defaults to noreply@weblate.org.

DEFAULT_COMMITER_NAME¶

New in version 2.4.

Default committer name when creating translation component (see Component configuration), defaults to Weblate.

DEFAULT_MERGE_STYLE¶

New in version 3.4.

Default merge style for new components (see Component configuration), choose one of:

rebase - default
merge

DEFAULT_TRANSLATION_PROPAGATION¶

New in version 2.5.

Default setting for translation propagation (see Component configuration), defaults to True.

See also

Component configuration

DEFAULT_PULL_MESSAGE¶

Default pull request title, defaults to 'Update from Weblate'.

ENABLE_AVATARS¶

Whether to enable Gravatar based avatars for users. By default this is enabled.

The avatars are fetched and cached on the server, so there is no risk in leaking private information or slowing down the user experiences with enabling this.

ENABLE_HOOKS¶

Whether to enable anonymous remote hooks.

See also

Notification hooks

ENABLE_HTTPS¶

Whether to send links to Weblate as https or http. This setting affects sent mails and generated absolute URLs.

See also

Version control integration

GITHUB_USERNAME¶

GitHub username that will be used to send pull requests for translation updates.

GOOGLE_ANALYTICS_ID¶

Google Analytics ID to enable monitoring of Weblate using Google Analytics.

HIDE_REPO_CREDENTIALS¶

Hide repository credentials in the web interface. In case you have repository URL with user and password, Weblate will hide it when showing it to the users.

For example instead of https://user:password@git.example.com/repo.git it will show just https://git.example.com/repo.git. It tries to cleanup VCS error messages as well in similar manner.

This is enabled by default.

IP_BEHIND_REVERSE_PROXY¶

New in version 2.14.

Indicates whether Weblate is running behind a reverse proxy.

If set to True, Weblate gets IP address from header defined by IP_BEHIND_REVERSE_PROXY. Ensure that you are actually using reverse proxy and that it sets this header, otherwise users will be able to fake the IP address.

Defaults to False.

IP_PROXY_HEADER¶

New in version 2.14.

Indicates from which header Weblate should obtain the IP address when IP_BEHIND_REVERSE_PROXY is enabled.

Defaults to HTTP_X_FORWARDED_FOR.

IP_PROXY_OFFSET¶

New in version 2.14.

Indicates which part of IP_BEHIND_REVERSE_PROXY is used as client IP address.

Depending on your setup, this header might consist of several IP addresses, (for example X-Forwarded-For: a, b, client-ip) and you can configure here which address from the header is client IP address.

Warning

Setting this affects security of your installation, you should only configure to use trusted proxies for determining IP address.

Defaults to 0.

LEGAL_URL¶

New in version 3.5.

URL where your Weblate instance shows it’s legal documents. This is useful if you host your legal documents outside Weblate for embedding inside Weblate please see Legal.

LIMIT_TRANSLATION_LENGTH_BY_SOURCE_LENGTH¶

By default the length of a given translation is limited to the length of the source string * 10 characters. Set this option to False to allow longer translations (up to 10.000 characters) irrespective of the source length.

Defaults to True.

LOGIN_REQUIRED_URLS_EXCEPTIONS¶

List of exceptions for LOGIN_REQUIRED_URLS. If you don’t specify this list, the default value will be used, which allows users to access the login page.

Some of exceptions you might want to include:

LOGIN_REQUIRED_URLS_EXCEPTIONS = (
    r'/accounts/(.*)$', # Required for login
    r'/static/(.*)$',   # Required for development mode
    r'/widgets/(.*)$',  # Allowing public access to widgets
    r'/data/(.*)$',     # Allowing public access to data exports
    r'/hooks/(.*)$',    # Allowing public access to notification hooks
    r'/api/(.*)$',      # Allowing access to API
    r'/js/i18n/$',      # JavaScript localization
)

MT_SERVICES¶

Changed in version 3.0: The setting was renamed from MACHINE_TRANSLATION_SERVICES to MT_SERVICES to be consistent with other machine translation settings.

List of enabled machine translation services to use.

Note

Many of services need additional configuration like API keys, please check their documentation for more details.

MT_SERVICES = (
    'weblate.machinery.apertium.ApertiumAPYTranslation',
    'weblate.machinery.deepl.DeepLTranslation',
    'weblate.machinery.glosbe.GlosbeTranslation',
    'weblate.machinery.google.GoogleTranslation',
    'weblate.machinery.microsoft.MicrosoftCognitiveTranslation',
    'weblate.machinery.microsoftterminology.MicrosoftTerminologyService',
    'weblate.machinery.mymemory.MyMemoryTranslation',
    'weblate.machinery.tmserver.AmagamaTranslation',
    'weblate.machinery.tmserver.TMServerTranslation',
    'weblate.machinery.yandex.YandexTranslation',
    'weblate.machinery.weblatetm.WeblateTranslation',
    'weblate.machinery.saptranslationhub.SAPTranslationHub',
    'weblate.memory.machine.WeblateMemory',
)

MT_APERTIUM_APY¶

URL of the Apertium APy server, see http://wiki.apertium.org/wiki/Apertium-apy

MT_AWS_ACCESS_KEY_ID¶

Access key ID for Amazon Translate.

MT_AWS_SECRET_ACCESS_KEY¶

API secret key for Amazon Translate.

MT_AWS_REGION¶

Region name to use for Amazon Translate.

MT_BAIDU_ID¶

Client ID for Baidu Zhiyun API, you can register at https://api.fanyi.baidu.com/api/trans/product/index

MT_BAIDU_SECRET¶

Client secret for Baidu Zhiyun API, you can register at https://api.fanyi.baidu.com/api/trans/product/index

MT_DEEPL_KEY¶

API key for DeepL API, you can register at https://www.deepl.com/pro.html.

MT_GOOGLE_KEY¶

API key for Google Translate API, you can register at https://cloud.google.com/translate/docs

MT_MICROSOFT_COGNITIVE_KEY¶

Client key for Microsoft Cognitive Services Translator API.

MT_MYMEMORY_EMAIL¶

MyMemory identification e-mail, you can get 1000 requests per day with this.

MT_MYMEMORY_KEY¶

MyMemory access key for private translation memory, use together with MT_MYMEMORY_USER.

MT_MYMEMORY_USER¶

MyMemory user id for private translation memory, use together with MT_MYMEMORY_KEY.

MT_NETEASE_KEY¶

App key for Netease Sight API, you can register at https://sight.netease.com/

MT_NETEASE_SECRET¶

App secret for Netease Sight API, you can register at https://sight.netease.com/

MT_TMSERVER¶

URL where tmserver is running.

MT_YANDEX_KEY¶

API key for Yandex Translate API, you can register at https://tech.yandex.com/translate/

MT_YOUDAO_ID¶

Client ID for Youdao Zhiyun API, you can register at https://ai.youdao.com/product-fanyi.s

MT_YOUDAO_SECRET¶

Client secret for Youdao Zhiyun API, you can register at https://ai.youdao.com/product-fanyi.s

MT_SAP_BASE_URL¶

API URL to the SAP Translation Hub service.

MT_SAP_SANDBOX_APIKEY¶

API key for sandbox API usage

MT_SAP_USERNAME¶

Your SAP username

MT_SAP_PASSWORD¶

Your SAP password

MT_SAP_USE_MT¶

Should the machine translation service also be used? (in addition to the term database). Possible values: True / False

NEARBY_MESSAGES¶

How many messages around current one to show during translating.

PIWIK_SITE_ID¶

ID of a site in Matomo you want to track.

See also

PIWIK_URL

PIWIK_URL¶

URL of a Matomo installation you want to use to track Weblate users. For more information about Matomo see <https://matomo.org/>.

See also

PIWIK_SITE_ID

REGISTRATION_CAPTCHA¶

A boolean (either True or False) indicating whether registration of new accounts is protected by captcha. This setting is optional, and a default of True will be assumed if it is not supplied.

If enabled the captcha is added to all pages where users enter e-mail address:

New account registration.
Password recovery.
Adding e-mail to an account.
Contact form for users who are not logged in.

REGISTRATION_EMAIL_MATCH¶

New in version 2.17.

Allows you to filter e-mail addresses which can register.

Defaults to .* which allows any address to register.

You can use it to restrict registration to a single e-mail domain:

REGISTRATION_EMAIL_MATCH = r'^.*@weblate\.org$'

REGISTRATION_OPEN¶

A boolean (either True or False) indicating whether registration of new accounts is currently permitted. This setting is optional, and a default of True will be assumed if it is not supplied.

SIMPLIFY_LANGUAGES¶

Use simple language codes for default language/country combinations. For example fr_FR translation will use fr language code. This is usually desired behavior as it simplifies listing of the languages for these default combinations.

Disable this if you are having different translations for both variants.

SITE_TITLE¶

Site title to be used in website and e-mails as well.

SPECIAL_CHARS¶

Additional chars to show in the visual keyboard, see Visual keyboard.

The default value is:

SPECIAL_CHARS = ('\t', '\n', '…')

SINGLE_PROJECT¶

New in version 3.8.

Redirect user directly to single project or component instead of showing dashboard.

STATUS_URL¶

URL where your Weblate instance reports it’s status.

SUGGESTION_CLEANUP_DAYS¶

New in version 3.2.1.

Automatically delete suggestions after given number of days. Defaults to None what means no deletion at all.

URL_PREFIX¶

This settings allows you to run Weblate under some path (otherwise it relies on being executed from webserver root). To use this setting, you also need to configure your server to strip this prefix. For example with WSGI, this can be achieved by setting WSGIScriptAlias.

Note

This setting does not work with Django’s builtin server, you would have to adjust urls.py to contain this prefix.

VCS_BACKENDS¶

Configuration of available VCS backends. Weblate tries to use all supported backends for which you have tools available. You can limit choices or add custom VCS backends using this.

VCS_BACKENDS = (
   'weblate.vcs.git.GitRepository',
)

See also

WEBLATE_ADDONS¶

List of addons available for use. To use them, they have to be enabled for given translation component. By default this includes all built in addons, when extending the list you will probably want to keep existing ones enabled, for example:

WEBLATE_ADDONS = (
    # Built in addons
    'weblate.addons.gettext.GenerateMoAddon',
    'weblate.addons.gettext.UpdateLinguasAddon',
    'weblate.addons.gettext.UpdateConfigureAddon',
    'weblate.addons.gettext.MsgmergeAddon',
    'weblate.addons.gettext.GettextCustomizeAddon',
    'weblate.addons.gettext.GettextAuthorComments',
    'weblate.addons.cleanup.CleanupAddon',
    'weblate.addons.consistency.LangaugeConsistencyAddon',
    'weblate.addons.discovery.DiscoveryAddon',
    'weblate.addons.flags.SourceEditAddon',
    'weblate.addons.flags.TargetEditAddon',
    'weblate.addons.flags.SameEditAddon',
    'weblate.addons.generate.GenerateFileAddon',
    'weblate.addons.json.JSONCustomizeAddon',
    'weblate.addons.properties.PropertiesSortAddon',
    'weblate.addons.git.GitSquashAddon',
    'weblate.addons.removal.RemoveComments',
    'weblate.addons.removal.RemoveSuggestions',

    # Addon you want to include
    'weblate.addons.example.ExampleAddon',
)

See also

Addons

WEBLATE_FORMATS¶

New in version 3.0.

List of file formats available for use, you can usually keep this on default value.

See also

Supported file formats

WEBLATE_GPG_IDENTITY¶

New in version 3.1.

Identity which should be used by Weblate to sign Git commits, for example:

WEBLATE_GPG_IDENTITY = 'Weblate <weblate@example.com>'

Warning

If you are going to change value of setting, it is advisable to clean the cache as the key information is cached for seven days. This is not necessary for initial setup as nothing is cached if this feature is not configured.

See also

Signing Git commits by GnuPG

Sample configuration¶

The following example is shipped as weblate/settings_example.py with Weblate:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2019 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#

from __future__ import unicode_literals

import os
import platform
from logging.handlers import SysLogHandler

#
# Django settings for Weblate project.
#

DEBUG = True

ADMINS = (
    # ('Your Name', 'your_email@example.com'),
)

MANAGERS = ADMINS

DATABASES = {
    'default': {
        # Use 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
        'ENGINE': 'django.db.backends.sqlite3',
        # Database name or path to database file if using sqlite3.
        'NAME': 'weblate.db',
        # Database user, not used with sqlite3.
        'USER': 'weblate',
        # Database password, not used with sqlite3.
        'PASSWORD': 'weblate',
        # Set to empty string for localhost. Not used with sqlite3.
        'HOST': '127.0.0.1',
        # Set to empty string for default. Not used with sqlite3.
        'PORT': '',
        # Customizations for databases
        'OPTIONS': {
            # In case of using an older MySQL server,
            # which has MyISAM as a default storage
            # 'init_command': 'SET storage_engine=INNODB',
            # Uncomment for MySQL older than 5.7:
            # 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
            # Set emoji capable charset for MySQL:
            # 'charset': 'utf8mb4',
        },
    }
}

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Data directory
DATA_DIR = os.path.join(BASE_DIR, 'data')

# Local time zone for this installation. Choices can be found here:
# http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
# although not all choices may be available on all operating systems.
# In a Windows environment this must be set to your system time zone.
TIME_ZONE = 'UTC'

# Language code for this installation. All choices can be found here:
# http://www.i18nguy.com/unicode/language-identifiers.html
LANGUAGE_CODE = 'en-us'

LANGUAGES = (
    ('ar', 'العربية'),
    ('az', 'Azərbaycan'),
    ('be', 'Беларуская'),
    ('be@latin', 'Biełaruskaja'),
    ('bg', 'Български'),
    ('br', 'Brezhoneg'),
    ('ca', 'Català'),
    ('cs', 'Čeština'),
    ('da', 'Dansk'),
    ('de', 'Deutsch'),
    ('en', 'English'),
    ('el', 'Ελληνικά'),
    ('en-gb', 'English (United Kingdom)'),
    ('es', 'Español'),
    ('fi', 'Suomi'),
    ('fr', 'Français'),
    ('gl', 'Galego'),
    ('he', 'עברית'),
    ('hu', 'Magyar'),
    ('id', 'Indonesia'),
    ('it', 'Italiano'),
    ('ja', '日本語'),
    ('kk', 'Қазақ тілі'),
    ('ko', '한국어'),
    ('nb', 'Norsk bokmål'),
    ('nl', 'Nederlands'),
    ('pl', 'Polski'),
    ('pt', 'Português'),
    ('pt-br', 'Português brasileiro'),
    ('ru', 'Русский'),
    ('sk', 'Slovenčina'),
    ('sl', 'Slovenščina'),
    ('sr', 'Српски'),
    ('sv', 'Svenska'),
    ('tr', 'Türkçe'),
    ('uk', 'Українська'),
    ('zh-hans', '简体字'),
    ('zh-hant', '正體字'),
)

SITE_ID = 1

# If you set this to False, Django will make some optimizations so as not
# to load the internationalization machinery.
USE_I18N = True

# If you set this to False, Django will not format dates, numbers and
# calendars according to the current locale.
USE_L10N = True

# If you set this to False, Django will not use timezone-aware datetimes.
USE_TZ = True

# URL prefix to use, please see documentation for more details
URL_PREFIX = ''

# Absolute filesystem path to the directory that will hold user-uploaded files.
# Example: "/home/media/media.lawrence.com/media/"
MEDIA_ROOT = os.path.join(DATA_DIR, 'media')

# URL that handles the media served from MEDIA_ROOT. Make sure to use a
# trailing slash.
# Examples: "http://media.lawrence.com/media/", "http://example.com/media/"
MEDIA_URL = '{0}/media/'.format(URL_PREFIX)

# Absolute path to the directory static files should be collected to.
# Don't put anything in this directory yourself; store your static files
# in apps' "static/" subdirectories and in STATICFILES_DIRS.
# Example: "/home/media/media.lawrence.com/static/"
STATIC_ROOT = os.path.join(DATA_DIR, 'static')

# URL prefix for static files.
# Example: "http://media.lawrence.com/static/"
STATIC_URL = '{0}/static/'.format(URL_PREFIX)

# Additional locations of static files
STATICFILES_DIRS = (
    # Put strings here, like "/home/html/static" or "C:/www/django/static".
    # Always use forward slashes, even on Windows.
    # Don't forget to use absolute paths, not relative paths.
)

# List of finder classes that know how to find static files in
# various locations.
STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'compressor.finders.CompressorFinder',
)

# Make this unique, and don't share it with anybody.
# You can generate it using weblate/examples/generate-secret-key
SECRET_KEY = 'jm8fqjlg+5!#xu%e-oh#7!$aa7!6avf7ud*_v=chdrb9qdco6('  # noqa

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            os.path.join(BASE_DIR, 'weblate', 'templates'),
        ],
        'OPTIONS': {
            'context_processors': [
                'django.contrib.auth.context_processors.auth',
                'django.template.context_processors.debug',
                'django.template.context_processors.i18n',
                'django.template.context_processors.request',
                'django.template.context_processors.csrf',
                'django.contrib.messages.context_processors.messages',
                'weblate.trans.context_processors.weblate_context',
            ],
            'loaders': [
                ('django.template.loaders.cached.Loader', [
                    'django.template.loaders.filesystem.Loader',
                    'django.template.loaders.app_directories.Loader',
                ]),
            ],
        },
    },
]


# GitHub username for sending pull requests.
# Please see the documentation for more details.
GITHUB_USERNAME = None

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.email.EmailAuth',
    # 'social_core.backends.google.GoogleOAuth2',
    # 'social_core.backends.github.GithubOAuth2',
    # 'social_core.backends.bitbucket.BitbucketOAuth',
    # 'social_core.backends.suse.OpenSUSEOpenId',
    # 'social_core.backends.ubuntu.UbuntuOpenId',
    # 'social_core.backends.fedora.FedoraOpenId',
    # 'social_core.backends.facebook.FacebookOAuth2',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Custom user model
AUTH_USER_MODEL = 'weblate_auth.User'

# Social auth backends setup
SOCIAL_AUTH_GITHUB_KEY = ''
SOCIAL_AUTH_GITHUB_SECRET = ''
SOCIAL_AUTH_GITHUB_SCOPE = ['user:email']

SOCIAL_AUTH_BITBUCKET_KEY = ''
SOCIAL_AUTH_BITBUCKET_SECRET = ''
SOCIAL_AUTH_BITBUCKET_VERIFIED_EMAILS_ONLY = True

SOCIAL_AUTH_FACEBOOK_KEY = ''
SOCIAL_AUTH_FACEBOOK_SECRET = ''
SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', 'public_profile']
SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {'fields': 'id,name,email'}
SOCIAL_AUTH_FACEBOOK_API_VERSION = '3.1'

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ''

# Social auth settings
SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.auth_allowed',
    'social_core.pipeline.social_auth.social_user',
    'weblate.accounts.pipeline.store_params',
    'weblate.accounts.pipeline.verify_open',
    'social_core.pipeline.user.get_username',
    'weblate.accounts.pipeline.require_email',
    'social_core.pipeline.mail.mail_validation',
    'weblate.accounts.pipeline.revoke_mail_code',
    'weblate.accounts.pipeline.ensure_valid',
    'weblate.accounts.pipeline.remove_account',
    'social_core.pipeline.social_auth.associate_by_email',
    'weblate.accounts.pipeline.reauthenticate',
    'weblate.accounts.pipeline.verify_username',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'weblate.accounts.pipeline.cleanup_next',
    'weblate.accounts.pipeline.user_full_name',
    'weblate.accounts.pipeline.store_email',
    'weblate.accounts.pipeline.notify_connect',
    'weblate.accounts.pipeline.password_reset',
)
SOCIAL_AUTH_DISCONNECT_PIPELINE = (
    'social_core.pipeline.disconnect.allowed_to_disconnect',
    'social_core.pipeline.disconnect.get_entries',
    'social_core.pipeline.disconnect.revoke_tokens',
    'weblate.accounts.pipeline.cycle_session',
    'weblate.accounts.pipeline.adjust_primary_mail',
    'weblate.accounts.pipeline.notify_disconnect',
    'social_core.pipeline.disconnect.disconnect',
    'weblate.accounts.pipeline.cleanup_next',
)

# Custom authentication strategy
SOCIAL_AUTH_STRATEGY = 'weblate.accounts.strategy.WeblateStrategy'

# Raise exceptions so that we can handle them later
SOCIAL_AUTH_RAISE_EXCEPTIONS = True

SOCIAL_AUTH_EMAIL_VALIDATION_FUNCTION = \
    'weblate.accounts.pipeline.send_validation'
SOCIAL_AUTH_EMAIL_VALIDATION_URL = \
    '{0}/accounts/email-sent/'.format(URL_PREFIX)
SOCIAL_AUTH_LOGIN_ERROR_URL = \
    '{0}/accounts/login/'.format(URL_PREFIX)
SOCIAL_AUTH_EMAIL_FORM_URL = \
    '{0}/accounts/email/'.format(URL_PREFIX)
SOCIAL_AUTH_NEW_ASSOCIATION_REDIRECT_URL = \
    '{0}/accounts/profile/#account'.format(URL_PREFIX)
SOCIAL_AUTH_PROTECTED_USER_FIELDS = ('email',)
SOCIAL_AUTH_SLUGIFY_USERNAMES = True
SOCIAL_AUTH_SLUGIFY_FUNCTION = 'weblate.accounts.pipeline.slugify_username'

# Password validation configuration
AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',  # noqa: E501, pylint: disable=line-too-long
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
        'OPTIONS': {
            'min_length': 6,
        }
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
    {
        'NAME': 'weblate.accounts.password_validation.CharsPasswordValidator',
    },
    {
        'NAME': 'weblate.accounts.password_validation.PastPasswordsValidator',
    },
    # Optional password strength validation by django-zxcvbn-password
    # {
    #     'NAME': 'zxcvbn_password.ZXCVBNValidator',
    #     'OPTIONS': {
    #         'min_score': 3,
    #         'user_attributes': ('username', 'email', 'full_name')
    #     }
    # },
]

# Allow new user registrations
REGISTRATION_OPEN = True

# Middleware
MIDDLEWARE = [
    'weblate.middleware.ProxyMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'weblate.accounts.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'social_django.middleware.SocialAuthExceptionMiddleware',
    'weblate.accounts.middleware.RequireLoginMiddleware',
    'weblate.middleware.SecurityMiddleware',
]

ROOT_URLCONF = 'weblate.urls'

# Django and Weblate apps
INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.admin.apps.SimpleAdminConfig',
    'django.contrib.admindocs',
    'django.contrib.sitemaps',
    'django.contrib.humanize',
    'social_django',
    'crispy_forms',
    'compressor',
    'rest_framework',
    'rest_framework.authtoken',
    'weblate.addons',
    'weblate.auth',
    'weblate.checks',
    'weblate.formats',
    'weblate.machinery',
    'weblate.trans',
    'weblate.lang',
    'weblate.langdata',
    'weblate.memory',
    'weblate.screenshots',
    'weblate.fonts',
    'weblate.accounts',
    'weblate.utils',
    'weblate.vcs',
    'weblate.wladmin',
    'weblate',

    # Optional: Git exporter
    # 'weblate.gitexport',
)

# Path to locales
LOCALE_PATHS = (os.path.join(BASE_DIR, 'weblate', 'locale'), )

# Custom exception reporter to include some details
DEFAULT_EXCEPTION_REPORTER_FILTER = \
    'weblate.trans.debug.WeblateExceptionReporterFilter'

# Default logging of Weblate messages
# - to syslog in production (if available)
# - otherwise to console
# - you can also choose 'logfile' to log into separate file
#   after configuring it below

# Detect if we can connect to syslog
HAVE_SYSLOG = False
if platform.system() != 'Windows':
    try:
        handler = SysLogHandler(
            address='/dev/log', facility=SysLogHandler.LOG_LOCAL2
        )
        handler.close()
        HAVE_SYSLOG = True
    except IOError:
        HAVE_SYSLOG = False

if DEBUG or not HAVE_SYSLOG:
    DEFAULT_LOG = 'console'
else:
    DEFAULT_LOG = 'syslog'

# A sample logging configuration. The only tangible logging
# performed by this configuration is to send an email to
# the site admins on every HTTP 500 error when DEBUG=False.
# See http://docs.djangoproject.com/en/stable/topics/logging for
# more details on how to customize your logging configuration.
LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse'
        }
    },
    'formatters': {
        'syslog': {
            'format': 'weblate[%(process)d]: %(levelname)s %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
        'logfile': {
            'format': '%(asctime)s %(levelname)s %(message)s'
        },
        'django.server': {
            '()': 'django.utils.log.ServerFormatter',
            'format': '[%(server_time)s] %(message)s',
        }
    },
    'handlers': {
        'mail_admins': {
            'level': 'ERROR',
            'filters': ['require_debug_false'],
            'class': 'django.utils.log.AdminEmailHandler',
            'include_html': True,
        },
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'simple'
        },
        'django.server': {
            'level': 'INFO',
            'class': 'logging.StreamHandler',
            'formatter': 'django.server',
        },
        'syslog': {
            'level': 'DEBUG',
            'class': 'logging.handlers.SysLogHandler',
            'formatter': 'syslog',
            'address': '/dev/log',
            'facility': SysLogHandler.LOG_LOCAL2,
        },
        # Logging to a file
        # 'logfile': {
        #     'level':'DEBUG',
        #     'class':'logging.handlers.RotatingFileHandler',
        #     'filename': "/var/log/weblate/weblate.log",
        #     'maxBytes': 100000,
        #     'backupCount': 3,
        #     'formatter': 'logfile',
        # },
    },
    'loggers': {
        'django.request': {
            'handlers': ['mail_admins', DEFAULT_LOG],
            'level': 'ERROR',
            'propagate': True,
        },
        'django.server': {
            'handlers': ['django.server'],
            'level': 'INFO',
            'propagate': False,
        },
        # Logging database queries
        # 'django.db.backends': {
        #     'handlers': [DEFAULT_LOG],
        #     'level': 'DEBUG',
        # },
        'weblate': {
            'handlers': [DEFAULT_LOG],
            'level': 'DEBUG',
        },
        # Logging search operations
        'weblate.search': {
            'handlers': [DEFAULT_LOG],
            'level': 'INFO',
        },
        # Logging VCS operations
        'weblate.vcs': {
            'handlers': [DEFAULT_LOG],
            'level': 'WARNING',
        },
        # Python Social Auth logging
        # 'social': {
        #     'handlers': [DEFAULT_LOG],
        #     'level': 'DEBUG',
        # },
    }
}

# Logging of management commands to console
if (os.environ.get('DJANGO_IS_MANAGEMENT_COMMAND', False)
        and 'console' not in LOGGING['loggers']['weblate']['handlers']):
    LOGGING['loggers']['weblate']['handlers'].append('console')

# Remove syslog setup if it's not present
if not HAVE_SYSLOG:
    del LOGGING['handlers']['syslog']

# List of machine translations
# MT_SERVICES = (
#     'weblate.machinery.apertium.ApertiumAPYTranslation',
#     'weblate.machinery.baidu.BaiduTranslation',
#     'weblate.machinery.deepl.DeepLTranslation',
#     'weblate.machinery.glosbe.GlosbeTranslation',
#     'weblate.machinery.google.GoogleTranslation',
#     'weblate.machinery.microsoft.MicrosoftCognitiveTranslation',
#     'weblate.machinery.microsoftterminology.MicrosoftTerminologyService',
#     'weblate.machinery.mymemory.MyMemoryTranslation',
#     'weblate.machinery.netease.NeteaseSightTranslation',
#     'weblate.machinery.tmserver.AmagamaTranslation',
#     'weblate.machinery.tmserver.TMServerTranslation',
#     'weblate.machinery.yandex.YandexTranslation',
#     'weblate.machinery.weblatetm.WeblateTranslation',
#     'weblate.machinery.saptranslationhub.SAPTranslationHub',
#     'weblate.machinery.youdao.YoudaoTranslation',
#     'weblate.memory.machine.WeblateMemory',
# )

# Machine translation API keys

# URL of the Apertium APy server
MT_APERTIUM_APY = None

# DeepL API key
MT_DEEPL_KEY = None

# Microsoft Cognitive Services Translator API, register at
# https://portal.azure.com/
MT_MICROSOFT_COGNITIVE_KEY = None

# MyMemory identification email, see
# https://mymemory.translated.net/doc/spec.php
MT_MYMEMORY_EMAIL = None

# Optional MyMemory credentials to access private translation memory
MT_MYMEMORY_USER = None
MT_MYMEMORY_KEY = None

# Google API key for Google Translate API
MT_GOOGLE_KEY = None

# Baidu app key and secret
MT_BAIDU_ID = None
MT_BAIDU_SECRET = None

# Youdao Zhiyun app key and secret
MT_YOUDAO_ID = None
MT_YOUDAO_SECRET = None

# Netease Sight (Jianwai) app key and secret
MT_NETEASE_KEY = None
MT_NETEASE_SECRET = None

# API key for Yandex Translate API
MT_YANDEX_KEY = None

# tmserver URL
MT_TMSERVER = None

# SAP Translation Hub
MT_SAP_BASE_URL = None
MT_SAP_SANDBOX_APIKEY = None
MT_SAP_USERNAME = None
MT_SAP_PASSWORD = None
MT_SAP_USE_MT = True

# Title of site to use
SITE_TITLE = 'Weblate'

# Whether site uses https
ENABLE_HTTPS = False

# Use HTTPS when creating redirect URLs for social authentication, see
# documentation for more details:
# https://python-social-auth-docs.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen
SOCIAL_AUTH_REDIRECT_IS_HTTPS = ENABLE_HTTPS

# Make CSRF cookie HttpOnly, see documentation for more details:
# https://docs.djangoproject.com/en/1.11/ref/settings/#csrf-cookie-httponly
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SECURE = ENABLE_HTTPS
# Store CSRF token in session
CSRF_USE_SESSIONS = True
# Customize CSRF failure view
CSRF_FAILURE_VIEW = 'weblate.trans.views.error.csrf_failure'
SESSION_COOKIE_SECURE = ENABLE_HTTPS
# SSL redirect
SECURE_SSL_REDIRECT = ENABLE_HTTPS
# SSL redirect URL exemption list
SECURE_REDIRECT_EXEMPT = (
    r'healthz/$',           # Allowing HTTP access to health check
)
# Session cookie age (in seconds)
SESSION_COOKIE_AGE = 1209600

# Some security headers
SECURE_BROWSER_XSS_FILTER = True
X_FRAME_OPTIONS = 'DENY'
SECURE_CONTENT_TYPE_NOSNIFF = True

# Optionally enable HSTS
SECURE_HSTS_SECONDS = 0
SECURE_HSTS_PRELOAD = False
SECURE_HSTS_INCLUDE_SUBDOMAINS = False

# URL of login
LOGIN_URL = '{0}/accounts/login/'.format(URL_PREFIX)

# URL of logout
LOGOUT_URL = '{0}/accounts/logout/'.format(URL_PREFIX)

# Default location for login
LOGIN_REDIRECT_URL = '{0}/'.format(URL_PREFIX)

# Anonymous user name
ANONYMOUS_USER_NAME = 'anonymous'

# Reverse proxy settings
IP_PROXY_HEADER = 'HTTP_X_FORWARDED_FOR'
IP_BEHIND_REVERSE_PROXY = False
IP_PROXY_OFFSET = 0

# Sending HTML in mails
EMAIL_SEND_HTML = True

# Subject of emails includes site title
EMAIL_SUBJECT_PREFIX = '[{0}] '.format(SITE_TITLE)

# Enable remote hooks
ENABLE_HOOKS = True

# Number of nearby messages to show in each direction
NEARBY_MESSAGES = 5

# By default the length of a given translation is limited to the length of
# the source string * 10 characters. Set this option to False to allow longer
# translations (up to 10.000 characters)
LIMIT_TRANSLATION_LENGTH_BY_SOURCE_LENGTH = True

# Use simple language codes for default language/country combinations
SIMPLIFY_LANGUAGES = True

# Render forms using bootstrap
CRISPY_TEMPLATE_PACK = 'bootstrap3'

# List of quality checks
# CHECK_LIST = (
#     'weblate.checks.same.SameCheck',
#     'weblate.checks.chars.BeginNewlineCheck',
#     'weblate.checks.chars.EndNewlineCheck',
#     'weblate.checks.chars.BeginSpaceCheck',
#     'weblate.checks.chars.EndSpaceCheck',
#     'weblate.checks.chars.EndStopCheck',
#     'weblate.checks.chars.EndColonCheck',
#     'weblate.checks.chars.EndQuestionCheck',
#     'weblate.checks.chars.EndExclamationCheck',
#     'weblate.checks.chars.EndEllipsisCheck',
#     'weblate.checks.chars.EndSemicolonCheck',
#     'weblate.checks.chars.MaxLengthCheck',
#     'weblate.checks.chars.KashidaCheck',
#     'weblate.checks.format.PythonFormatCheck',
#     'weblate.checks.format.PythonBraceFormatCheck',
#     'weblate.checks.format.PHPFormatCheck',
#     'weblate.checks.format.CFormatCheck',
#     'weblate.checks.format.PerlFormatCheck',
#     'weblate.checks.format.JavaScriptFormatCheck',
#     'weblate.checks.format.CSharpFormatCheck',
#     'weblate.checks.format.JavaFormatCheck',
#     'weblate.checks.format.JavaMessageFormatCheck',
#     'weblate.checks.angularjs.AngularJSInterpolationCheck',
#     'weblate.checks.qt.QtFormatCheck',
#     'weblate.checks.qt.QtPluralCheck',
#     'weblate.checks.ruby.RubyFormatCheck',
#     'weblate.checks.consistency.PluralsCheck',
#     'weblate.checks.consistency.SamePluralsCheck',
#     'weblate.checks.consistency.ConsistencyCheck',
#     'weblate.checks.consistency.TranslatedCheck',
#     'weblate.checks.chars.NewlineCountingCheck',
#     'weblate.checks.markup.BBCodeCheck',
#     'weblate.checks.chars.ZeroWidthSpaceCheck',
#     'weblate.checks.render.MaxSizeCheck',
#     'weblate.checks.markup.XMLValidityCheck',
#     'weblate.checks.markup.XMLTagsCheck',
#     'weblate.checks.markup.MarkdownRefLinkCheck',
#     'weblate.checks.markup.MarkdownLinkCheck',
#     'weblate.checks.markup.MarkdownSyntaxCheck',
#     'weblate.checks.markup.URLCheck',
#     'weblate.checks.source.OptionalPluralCheck',
#     'weblate.checks.source.EllipsisCheck',
#     'weblate.checks.source.MultipleFailingCheck',
# )

# List of automatic fixups
# AUTOFIX_LIST = (
#     'weblate.trans.autofixes.whitespace.SameBookendingWhitespace',
#     'weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis',
#     'weblate.trans.autofixes.chars.RemoveZeroSpace',
#     'weblate.trans.autofixes.chars.RemoveControlChars',
# )

# List of enabled addons
# WEBLATE_ADDONS = (
#     'weblate.addons.gettext.GenerateMoAddon',
#     'weblate.addons.gettext.UpdateLinguasAddon',
#     'weblate.addons.gettext.UpdateConfigureAddon',
#     'weblate.addons.gettext.MsgmergeAddon',
#     'weblate.addons.gettext.GettextCustomizeAddon',
#     'weblate.addons.gettext.GettextAuthorComments',
#     'weblate.addons.cleanup.CleanupAddon',
#     'weblate.addons.consistency.LangaugeConsistencyAddon',
#     'weblate.addons.discovery.DiscoveryAddon',
#     'weblate.addons.flags.SourceEditAddon',
#     'weblate.addons.flags.TargetEditAddon',
#     'weblate.addons.flags.SameEditAddon',
#     'weblate.addons.generate.GenerateFileAddon',
#     'weblate.addons.json.JSONCustomizeAddon',
#     'weblate.addons.properties.PropertiesSortAddon',
#     'weblate.addons.git.GitSquashAddon',
#     'weblate.addons.removal.RemoveComments',
#     'weblate.addons.removal.RemoveSuggestions',
# )

# E-mail address that error messages come from.
SERVER_EMAIL = 'noreply@example.com'

# Default email address to use for various automated correspondence from
# the site managers. Used for registration emails.
DEFAULT_FROM_EMAIL = 'noreply@example.com'

# List of URLs your site is supposed to serve
ALLOWED_HOSTS = []

# Example configuration for caching
# CACHES = {
#     'default': {
#         'BACKEND': 'django_redis.cache.RedisCache',
#         'LOCATION': 'redis://127.0.0.1:6379/0',
#         # If redis is running on same host as Weblate, you might
#         # want to use unix sockets instead:
#         # 'LOCATION': 'unix:///var/run/redis/redis.sock?db=0',
#         'OPTIONS': {
#             'CLIENT_CLASS': 'django_redis.client.DefaultClient',
#             'PARSER_CLASS': 'redis.connection.HiredisParser',
#         }
#     },
#     'avatar': {
#         'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
#         'LOCATION': os.path.join(DATA_DIR, 'avatar-cache'),
#         'TIMEOUT': 3600,
#         'OPTIONS': {
#             'MAX_ENTRIES': 1000,
#         },
#     }
# }

# REST framework settings for API
REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly'
    ],
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.TokenAuthentication',
        'weblate.api.authentication.BearerAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ),
    'DEFAULT_THROTTLE_CLASSES': (
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ),
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day'
    },
    'DEFAULT_PAGINATION_CLASS': (
        'rest_framework.pagination.PageNumberPagination'
    ),
    'PAGE_SIZE': 20,
    'VIEW_DESCRIPTION_FUNCTION': 'weblate.api.views.get_view_description',
    'UNAUTHENTICATED_USER': 'weblate.auth.models.get_anonymous',
}

# Example for restricting access to logged in users
# LOGIN_REQUIRED_URLS = (
#     r'/(.*)$',
# )

# In such case you will want to include some of the exceptions
# LOGIN_REQUIRED_URLS_EXCEPTIONS = (
#    r'/accounts/(.*)$',        # Required for login
#    r'/admin/login/(.*)$',     # Required for admin login
#    r'/static/(.*)$',          # Required for development mode
#    r'/widgets/(.*)$',         # Allowing public access to widgets
#    r'/data/(.*)$',            # Allowing public access to data exports
#    r'/hooks/(.*)$',           # Allowing public access to notification hooks
#    r'/healthz/$',             # Allowing public access to health check
#    r'/api/(.*)$',             # Allowing access to API
#    r'/js/i18n/$',             # JavaScript localization
#    r'/contact/$',             # Optional for contact form
#    r'/legal/(.*)$',           # Optional for legal app
# )

# Silence some of the Django system checks
SILENCED_SYSTEM_CHECKS = [
    # We have modified django.contrib.auth.middleware.AuthenticationMiddleware
    # as weblate.accounts.middleware.AuthenticationMiddleware
    'admin.E408',
]

# Celery worker configuration for testing
CELERY_TASK_ALWAYS_EAGER = True
CELERY_BROKER_URL = 'memory://'
CELERY_TASK_EAGER_PROPAGATES = True
# Celery worker configuration for production
# CELERY_TASK_ALWAYS_EAGER = False
# CELERY_BROKER_URL = 'redis://localhost:6379'
# CELERY_RESULT_BACKEND = CELERY_BROKER_URL

# Celery settings, it is not recommended to change these
CELERY_WORKER_PREFETCH_MULTIPLIER = 0
CELERY_WORKER_MAX_MEMORY_PER_CHILD = 200000
CELERY_BEAT_SCHEDULE_FILENAME = os.path.join(
    DATA_DIR, 'celery', 'beat-schedule'
)
CELERY_TASK_ROUTES = {
    'weblate.trans.search.*': {'queue': 'search'},
    'weblate.trans.tasks.optimize_fulltext': {'queue': 'search'},
    'weblate.trans.tasks.cleanup_fulltext': {'queue': 'search'},
    'weblate.memory.tasks.*': {'queue': 'memory'},
    'weblate.accounts.tasks.notify_change': {'queue': 'notify'},
    'weblate.accounts.tasks.send_mails': {'queue': 'notify'},
}

Management commands¶

Note

Running management commands under a different user than is running your webserver can cause wrong permissions on some files, please check Filesystem permissions for more details.

Django comes with a management script (available as ./manage.py in sources or installed as weblate when Weblate is installed). It provides various management commands and Weblate extends it with several additional commands.

Invoking management commands¶

As mentioned before, invocation depends on how you have installed Weblate.

If you are using source code directly (either tarball or Git checkout), the management script is ./manage.py in Weblate sources. Execution can be done as:

python ./manage.py list_versions

If you’ve installed Weblate using PIP installer or by ./setup.py script, the weblate is installed to your path and you can use it to control Weblate:

weblate list_versions

For Docker image, the script is installed same as above, you can execute it using docker exec:

docker exec --user weblate <container> weblate list_versions

With docker-compose this is quite similar, you just have to use docker-compose exec:

docker-compose exec --user weblate weblate weblate list_versions

In case you need to pass some file, you can temporary add a volume:

docker-compose exec --user weblate /tmp:/tmp weblate weblate importusers /tmp/users.json

Installing from sources, recommended for development.

add_suggestions¶

manage.py add_suggestions <project> <component> <language> <file>¶

New in version 2.5.

Imports translation from the file as a suggestion to given translation. It skips translations which are the same as existing ones, only different ones are added.

--author USER@EXAMPLE.COM¶: Email of author for the suggestions. This user has to exist prior importing (you can create one in the admin interface if needed).

Example:

./manage.py --author michal@cihar.com add_suggestions weblate master cs /tmp/suggestions-cs.po

auto_translate¶

manage.py auto_translate <project> <component> <language>¶

New in version 2.5.

Performs automatic translation based on other component translations.

--source PROJECT/COMPONENT¶: Specifies component to use as source for translation. If not specified all components in the project are used.

--user USERNAME¶: Specify username who will be author of the translations. Anonymous user is used if not specified.

--overwrite¶: Whether to overwrite existing translations.

--inconsistent¶: Whether to overwrite existing translations which are inconsistent (see Inconsistent).

--add¶: Automatically add language if given translation does not exist.

--mt MT¶: Use machine translation instead of other components.

--threshold THRESHOLD¶: Similarity threshold for machine translation, defaults to 80.

Example:

./manage.py --user nijel --inconsistent --source phpmyadmin/master phpmyadmin 4-5 cs

See also

Automatic translation

celery_queues¶

manage.py celery_queues¶

New in version 3.7.

Displays length of Celery task queues.

changesite¶

manage.py changesite¶

New in version 2.4.

You can use this to change or display site name from command line without using admin interface.

--set-name NAME¶: Sets name for the site.

--get-name¶: Prints currently configured site name.

See also

Running maintenance tasks

checkgit¶

manage.py checkgit <project|project/component>¶

Prints current state of the backend git repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

commitgit¶

manage.py commitgit <project|project/component>¶

Commits any possible pending changes to backend git repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

commit_pending¶

manage.py commit_pending <project|project/component>¶

Commits pending changes older than given age.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

--age HOURS¶: Age in hours for committing. If not specified value configured in Component configuration is used.

Note

This is automatically perfomed in the background by Weblate, so there is not much reason to invoke this manually besides forcing earlier commit than specified by Component configuration.

cleanup_avatar_cache¶

New in version 3.1.

manage.py cleanup_avatar_cache¶

Removes invalid items in avatar cache. This can be useful when switching between Python 2 and 3 as the cache files might be not compatible.

cleanuptrans¶

manage.py cleanuptrans¶

Cleanups orphaned checks and translation suggestions. This is normally not needed to execute manually, the cleanups happen automatically in the background.

See also

createadmin¶

manage.py createadmin¶

Creates admin account with random password unless it is specified.

--password PASSWORD¶: Provide password on the command line and skip generating random one.

--no-password¶: Do not set password, this can be useful with –update.

--username USERNAME¶: Use given name instead of admin.

--email USER@EXAMPLE.COM¶: Specify admin e-mail.

--name¶: Specify admin name (visible).

--update¶: Update existing user (you can use this to change password).

Changed in version 2.9: Added parameters --username, --email, --name and --update.

delete_memory¶

manage.py delete_memory¶

New in version 2.20.

Deletes entries in the Weblate Translation Memory.

--origin ORIGIN¶: Origin to delete, for imported files the origin is filename without path.

--all¶: Delete complete memory content and recreate the database.

See also

dump_memory¶

manage.py dump_memory¶

New in version 2.20.

Export a JSON file with the Weblate Translation Memory content.

See also

dumpuserdata¶

manage.py dumpuserdata <file.json>¶

Dumps userdata to file for later use by importuserdata

This is useful when migrating or merging Weblate instances.

import_json¶

manage.py import_json <json-file>¶

New in version 2.7.

Batch import of components based on JSON data.

The imported JSON file structure pretty much corresponds to the component object (see GET /api/components/(string:project)/(string:component)/). You always have to include fields name and filemask.

--project PROJECT¶: Specifies where the components will be imported.

--main-component COMPONENT¶: Use VCS repository from this component for all.

--ignore¶: Skip already imported components.

--update¶: Update already imported components.

Changed in version 2.9: Added parameters --ignore and --update to deal with already imported components.

Example of JSON file:

[
    {
        "slug": "po",
        "name": "Gettext PO",
        "file_format": "po",
        "filemask": "po/*.po",
        "new_lang": "none"
    },
    {
        "name": "Android",
        "filemask": "android/values-*/strings.xml",
        "template": "android/values/strings.xml",
        "repo": "weblate://test/test",
        "file_format": "aresource"
    }
]

See also

import_memory

import_memory¶

manage.py import_memory <file>¶

New in version 2.20.

Imports a TMX or JSON file into the Weblate Translation Memory.

--language-map LANGMAP¶

Allows to map languages in the TMX to Weblate one. The language codes are mapped after normalization usually done by Weblate.

For example --language-map en_US:en will import all en_US strings as en ones.

This can be useful in case your TMX file locales does not match what you use in Weblate.

See also

import_project¶

manage.py import_project <project> <gitrepo> <branch> <filemask>¶

Changed in version 3.0: The import_project command is now based on the Component discovery addon and that has lead to some changes in behavior and accepted parameters.

Batch imports components into project based on file mask.

<project> names an existing project, into which the components should be imported.

The <gitrepo> defines URL of Git repository to use, and <branch> the git branch. To import additional translation components, from an existing Weblate component, use a weblate://<project>/<component> URL for the <gitrepo>.

The <filemask> defines files discovery in the repository. It can be either simple using wildcards or it can use full power of regular expressions.

The simple matching uses ** for component name and * for language, for example: **/*.po

The regular expression has to contain named groups component and language. For example: (?P<language>[^/]*)/(?P<component>[^-/]*)\.po

The import matches existing components based on files and adds the ones which do not exist. It does no changes to the already existing ones.

--name-template TEMPLATE¶

Customize the component’s name, using Django template syntax.

For example: Documentation: {{ component }}

--base-file-template TEMPLATE¶

Customize base file for monolingual translations.

For example: {{ component }}/res/values/string.xml

--new-base-template TEMPLATE¶

Customize base file for adding new translations.

For example: {{ component }}/ts/en.ts

--file-format FORMAT¶: You can also specify file format to use (see Supported file formats), the default is autodetection.

--language-regex REGEX¶: You can specify language filtering (see Component configuration) by this parameter. It has to be valid regular expression.

--main-component¶: You can specify which component will be chosen as main - the one actually containing VCS repository.

--license NAME¶: Specify translation license.

--license-url URL¶: Specify translation license URL.

--vcs NAME¶: In case you need to specify version control system to use, you can do it here. The default version control is Git.

To give you some examples, let’s try importing two projects.

As first we import The Debian Handbook translations, where each language has separate folder with translations of each chapter:

./manage.py import_project \
    debian-handbook \
    git://anonscm.debian.org/debian-handbook/debian-handbook.git \
    squeeze/master \
    '*/**.po'

Another example can be Tanaguru tool, where we need to specify file format, base file template and has all components and translations located in single folder:

./manage.py import_project \
    --file-format=properties \
    --base-file-template=web-app/tgol-web-app/src/main/resources/i18n/%s-I18N.properties \
    tanaguru \
    https://github.com/Tanaguru/Tanaguru \
    master \
    web-app/tgol-web-app/src/main/resources/i18n/**-I18N_*.properties

Example of more complex parsing of filenames to get correct component and language out of filename like src/security/Numerous_security_holes_in_0.10.1.de.po:

./manage.py import_project \
    tails \
    git://git.tails.boum.org/tails master \
    'wiki/src/security/(?P<component>.*)\.(?P<language>[^.]*)\.po$'

Filtering only translations in chosen language:

./manage import_project \
    --language-regex '^(cs|sk)$' \
    weblate \
    https://github.com/WeblateOrg/weblate.git \
    'weblate/locale/*/LC_MESSAGES/**.po'

See also

More detailed examples can be found in the Starting with internationalization chapter, alternatively you might want to use import_json.

importuserdata¶

manage.py importuserdata <file.json>¶

Imports userdata from file created by dumpuserdata

importusers¶

manage.py importusers --check <file.json>¶

Imports users from JSON dump of Django auth_users database.

--check¶: With this option it will just check whether given file can be imported and report possible conflicts on usernames or e-mails.

You can dump users from existing Django installation using:

./manage.py dumpdata auth.User > users.json

install_addon¶

New in version 3.2.

manage.py install_addon --addon ADDON <project|project/component>¶

Installs addon to set of components.

--addon ADDON¶: Name of addon to install. For example weblate.gettext.customize.

--configuration CONFIG¶: JSON encoded configuration of an addon.

--update¶: Update existing addon configuration.

You can either define on which project or component to install addon (eg. weblate/master) or use --all to include all existing components.

For example installing Customize gettext output to all components:

./manage.py install_addon --addon weblate.gettext.customize --config '{"width": -1}' --update --all

See also

Addons

list_ignored_checks¶

manage.py list_ignored_checks¶

Lists most frequently ignored checks. This can be useful for tuning your setup, if users have to ignore too many of consistency checks.

list_languages¶

manage.py list_languages <locale>¶

Lists supported language in MediaWiki markup - language codes, English names and localized names.

This is used to generate <https://wiki.l10n.cz/Jazyky>.

list_memory¶

manage.py list_memory¶

New in version 2.20.

Lists contents of the Weblate Translation Memory.

--type {origin}¶: Type of information to list, defaults to listing used origins.

See also