Weblate is a copylefted libre software web-based continuous localization system, used by over 1150 libre projects and companies in more than 115 countries.

Install it, or use the Hosted Weblate service at weblate.org.

https://readthedocs.org/projects/weblate/badge/

Documentation¶

To be found in the docs directory the source code, or viewed online on https://docs.weblate.org/

Installation¶

Setup instructions:

https://docs.weblate.org/en/latest/admin/quick.html

Bugs¶

Please report feature requests and problems to:

https://github.com/WeblateOrg/weblate/issues

License¶

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/.

Weblate basics¶

Project structure¶

In Weblate translations are organized into projects and components. Each project can contain number of components and those contain translations into individual languages. The component corresponds to one translatable file (for example GNU gettext or Android string resources). The projects are there to help you organize component into logical sets (for example to group all translations used within one application).

Internally, each project has translations to common strings propagated across other components within it by default. This lightens the burden of repetitive and multi version translation. Disable it as per Component configuration, still producing errors for seemingly inconsistent resulting translations.

Registration and user profile¶

Registration¶

Everybody can browse projects, view translations or suggest translations by default. Only registered users are allowed to actually save changes, and are credited for every translation made.

You can register by following a few simple steps:

Fill out the registration form with your credentials.
Activate registration by following the link in the e-mail you receive.
Optionally adjust your profile to choose which languages you know.

Dashboard¶

When you sign in, you will see an overview of projects and components, as well as their respective translation progression.

New in version 2.5.

Components of projects you are watching are shown by default, and cross-referenced with your preferred languages.

Hint

You can switch to different views using the navigation tabs.

The menu has these options:

Projects > Browse all projects in the main menu showing translation status for each project on the Weblate instance.
Selecting a language in the main menu Languages will show translation status of all projects, filtered by one of your primary languages.
Watched translations in the Dashboard will show translation status of only those projects you are watching, filtered by your primary languages.

In addition, the drop-down can also show any number of component lists, sets of project components preconfigured by the Weblate administrator, see Component Lists.

You can configure your personal default dashboard view in the Preferences section of your user profile settings.

Note

When Weblate is configured for a single project using SINGLE_PROJECT in the settings.py file (see Configuration), the dashboard will not be shown, as the user will be redirected to a single project or component instead.

User profile¶

The user profile is accessible by clicking your user icon in the top-right of the top menu, then the Settings menu.

The user profile contains your preferences. Name and e-mail address is used in VCS commits, so keep this info accurate.

Note

All language selections only offer currently translated languages.

Hint

Request or add other languages you want to translate by clicking the button to make them available too.

Translated languages¶

Choose which languages you prefer to translate, and they will be offered on the main page of watched projects, so that you have easier access to these all translations in each of those languages.

Secondary languages¶

You can define which secondary languages are shown to you as a guide while translating. An example can be seen in the following image, where the Hebrew language is shown as secondarily:

Default dashboard view¶

On the Preferences tab, you can pick which of the available dashboard views to present by default. If you pick the Component list, you have to select which component list will be displayed from the Default component list drop-down.

See also

Component Lists

Avatar¶

Avatar can be shown for each user (depending on ENABLE_AVATARS). These images are obtained using https://gravatar.com/.

Editor link¶

A source code link is shown in the web-browser configured in the Component configuration by default.

Hint

By setting the Editor link, you use your local editor to open the VCS source code file of translated strings. You can use Template markup.

Usually something like editor://open/?file={{filename}}&line={{line}} is a good option.

See also

You can find more info on registering custom URL protocols for the editor in the Nette documentation.

Notifications¶

Subscribe to various notifications from the Subscriptions tab. Notifications for selected events on watched or administered projects will be sent to you per e-mail.

Some of the notifications are sent only for events in your languages (for example about new strings to translate), while some trigger at component level (for example merge errors). These two groups of notifications are visually separated in the settings.

You can toggle notifications for watched projects and administered projects and it can be further tweaked (or muted) per project and component. Visit the component page and select appropriate choice from the Watching menu.

Note

You will not receive notifications for your own actions.

Account¶

The Account tab lets you set up basic account details, connect various services you can use to sign in into Weblate, completely remove your account, or download your user data.

Note

The list of services depends on your Weblate configuration, but can be made to include popular sites such as GitLab, GitHub, Google, Facebook, or Bitbucket or other OAuth 2.0 providers.

Translating using Weblate¶

Thank you for interest in translating using Weblate. Projects can either be set up for direct translation, or by way of accepting suggestions made by users without accounts.

Overall, there are two modes of translation:

The project accepts direct translations
The project accepts only suggestions, which are automatically validated once a defined number of votes is reached

Please see Translation workflows for more information on translation workflow.

Options for translation project visibility:

Publicly visible and anybody can contribute
Visible only to a certain group of translators

See also

Access control, Translation workflows

Translation projects¶

Translation projects hold related components, related to the same software, book, or project.

Translation links¶

Having navigated to a component, a set of links lead to actual translation. The translation is further divided into individual checks, like Untranslated or Needing review. If the whole project is translated, without error, All translations is still available. Alternatively you can use the search field to find a specific string or term.

Suggestions¶

Note

Actual permissions might vary depending on your Weblate configuration.

Anonymous users can only (if permitted) forward suggestions. Doing so is still available to signed in users, in cases where uncertainty about the translation arises, which will prompt another translator to review it.

The suggestions are scanned on a daily basis to remove duplicate ones or suggestions that match the current translation.

Comments¶

The comments can be posted in two scopes - source string or translation. Choose the one which matches the topic you want to discuss. The source string comments are good for prividing feedback on the original string, for example that it should be rephrased or it is confusing.

You can use Markdown syntax in the comments and mention other users using @mention.

Shapings¶

Shapings are used to group variants of the string in different lengths. The frontend can use different strings depending on the screen or window size.

See also

String shapings

Labels¶

Labels are used to categorize strings within a project. These can be used to further customize the localization workflow, for example to define categories of strings.

See also

String labels

Translating¶

On the translation page, the source string and an edit area for translating are shown. Should the translation be plural, multiple source strings and edit areas are shown, each described and labeled in plural form.

All special whitespace characters are underlined in red and indicated with grey symbols. More than one subsequent space is also underlined in red to alert the translator to a potential formatting issue.

Various bits of extra information can be shown on this page, most of which coming from the project source code (like context, comments or where the message is being used). When you choose secondary languages in your preferences, translation to these languages will be shown (see Secondary languages) above the source string.

Below the translation, any suggestion made by others will be shown, which you can in turn accept, accept with changes, or delete.

Plurals¶

Words that change form to account of their numeric designation are called plurals. Each language has its own definition of plurals. English, for example, supports one plural. In the singular definition of for example “car”, implicitly one car is referenced, in the plural definition, “cars” two or more cars are referenced, or the concept of cars as a noun. Languages like for example Czech or Arabic have more plurals and also their rules for plurals are different.

Weblate has full support for each of these forms, in each respective language by translating every plural separately. The number of fields and how it is used in the translated application depends on the configured plural formula. Weblate shows the basic information, but you can find a more detailed description in the Language Plural Rules by the Unicode Consortium.

See also

Plural formula

Keyboard shortcuts¶

Changed in version 2.18: The keyboard shortcuts have been revamped in 2.18 to less likely collide with browser or system defaults.

The following keyboard shortcuts can be utilized during translation:

Alt+Home: Navigates to first translation in current search.
Alt+End: Navigates to last translation in current search.
Alt+PageUp: Navigates to previous translation in current search.
Alt+PageDown: Navigates to next translation in current search.
Ctrl+Enter or Option+Enter: Saves current translation.
Ctrl+Shift+Enter or Option+Shift+Enter: Unmarks translation as fuzzy and submits it.
Ctrl+E or Option+E: Focus translation editor.
Ctrl+U or Option+U: Focus comment editor.
Ctrl+M or Option+M: Shows machine translation tab.
Ctrl+<NUMBER> or Option+<NUMBER>: Copies placeable of given number from source string.
Ctrl+M <NUMBER> or Option+M <NUMBER>: Copy machine translation of given number to current translation.
Ctrl+I <NUMBER> or Option+I <NUMBER>: Ignore failing check of given number.
Ctrl+J or Option+J: Shows nearby strings tab.
Ctrl+S or Option+S: Shows search tab.
Ctrl+O or Option+O: Copies source string.
Ctrl+T or Option+T: Toggles “Needs editing” flag.

Visual keyboard¶

A small visual keyboard is shown just above the translation field. This can be useful for typing characters not usually found or otherwise hard to type.

The shown symbols factor into three categories:

User configured characters defined in the User profile
Per language characters provided by Weblate (e.g. quotes or RTL specific characters)
Chars configured using SPECIAL_CHARS

Translation context¶

This contextual description provides related information about the current string.

String attributes: Things like message ID, context (msgctxt) or location in source code.
Screenshots: Screenshots can be uploaded to Weblate to better inform translators of where and how the string is used, see Visual context for strings.
Nearby strings: Displays neighbouring messages from the translation file. These are usually also used in a similar context and prove useful in keeping the translation consistent.
Other occurences: In case a message appears in multiple places (e.g. multiple components), this tab shows all of them if they are found to be inconsistent (see Inconsistent). You can choose which one to use.
Translation memory: Look at similar strings translated in past, see Memory Management.
Glossary: Displays terms from the project glossary used in the current message.
Recent edits: List of people whom have changed this message recently using Weblate.
Project: Project information like instructions for translators, or information about its version control system repository.

If the translation format supports it, you can also follow supplied links to respective source code containing each source string.

Translation history¶

Every change is by default (unless turned off in component settings) saved in the database, and can be reverted. Optionally one can still also revert anything in the underlying version control system.

Translated string length¶

Weblate can limit length of translation in several ways to ensure the translated string is not too long:

The default limitation for translation is ten times longer than source string. This can be turned of by LIMIT_TRANSLATION_LENGTH_BY_SOURCE_LENGTH. In case you are hitting this, it might be also caused by monolingual translation being configured as bilingual, making Weblate see translation key as source string instead of the actual source string. See Bilingual and monolingual formats for more info.
Maximal length in characters defined by translation file or flag, see Maximum length.
Maximal rendered size in pixels defined by flags, see Maximum size of translation.

Glossary¶

Each project can have an assigned glossary for any language as a shorthand for storing terminology. Consistency is more easily maintained this way. Terms from the currently translated string can be displayed in the bottom tabs.

Managing glossaries¶

On the Glossaries tab of each project page, you can edit existing glossaries. An empty glossary for a given project is automatically created when a language is added to a component (to do this, select a component, its Translation tab and click Start new translation). Once a glossary exists, it will also show up in this list.

Glossaries are shared among all components of the same project.

On this list, you can choose which glossary to manage (all languages used in the current project are shown). Following one of the language links will lead you to a page which can be used to edit, import or export the selected glossary, or view the edit history:

Machine translation¶

Based on configuration and your translated language, Weblate provides you suggestions from several machine translation tools. All machine translations are available in a single tab of each translation page.

See also

You can find the list of supported tools in Machine translation.

Automatic translation¶

You can use automatic translation to bootstrap translation based on external sources. This tool is called Automatic translation accessible in the Tools menu, once you have selected a component and a language:

Two modes of operation are possible:

Using other Weblate components as a source for translations.
Using selected machine translation services with translations above a certain quality threshold.

You can also choose which strings are to be auto-translated.

Warning

Be mindful that this will overwrite existing translations if employed with wide filters such as All strings.

Useful in several situations like consolidating translation between different components (for example website and application) or when bootstrapping translation for a new component using existing translations (translation memory).

Rate limiting¶

To avoid abuse of the interface, there is rate limiting applied to several operations like searching, sending contact form or translating. In case you are are hit by this, you are blocked for a certain period until you can perform the operation again.

The default limits are described in the administrative manual in Rate limiting, but can be tweaked by configuration.

Downloading and uploading translations¶

You can export files from a translation, make changes, and import them again. This allows working offline, and then merging changes back into the existing translation. This works even if it has been changed in the meantime.

Note

The available options might be limited by Access control.

Downloading translations¶

From the project or component dashboard, translatable files can be downloaded using the Download source file in the Files menu, producing a copy of the file as it is stored in the upstream Version Control System.

You can either download the original file as is or converted into one of widely used localization formats. The converted files will be enriched with data provided in Weblate such as additional context, comments or flags.

Several file formats are available, including a compiled file to use in your choice of application (for example .mo files for GNU Gettext) using the Files menu.

Uploading translations¶

When you have made your changes, use Upload translation in the Files menu.

Supported file formats¶

Any file in a supported file format can be uploaded, but it is still recommended to use the same file format as the one used for translation, otherwise some features might not be translated properly.

See also

Supported file formats

The uploaded file is merged to update the translation, overwriting existing entries by default (this can be turned off or on in the upload dialog).

Import methods¶

These are the choices presented when uploading translation files:

Add as translation: Imported translations are added as translations. This is the most common usecase, and the default behavior.
Add as suggestion: Imported translations are added as suggestions, do this when you want to have your uploaded strings reviewed.
Add as translation needing edit: Imported translations are added as translations needing edit. This can be useful when you want translations to be used, but also reviewed.
Replace existing translation file: Existing file is replaced with new content. This can lead to loss of existing translations, use with caution.
Update source strings: Updates source strings in bilingual translation file. This is similar to what Update PO files to match POT (msgmerge) does.

Strings needing edit¶

There is also an option for how to handle strings needing edit in the imported file. Such strings can be handle in one of the three following ways: “Do not import”, “Import as string needing edit”, or “Import as translated”.

Overriding authorship¶

With admin permissions, you can also specify authorship of uploaded file. This can be useful in case you’ve received the file in another way and want to merge it into existing translations while properly crediting the actual author.

Checks and fixups¶

The quality checks help catch common translator errors, ensuring the translation is in good shape. The checks are divided into three levels of severity, and can be ignored in case of false positives.

Once submitting a translation with a failing check, this is immediately shown to the user:

Automatic fixups¶

In addition to Quality checks, Weblate can also fix some common errors in translated strings automatically. Use it with caution to not have it add errors.

See also

AUTOFIX_LIST

Quality checks¶

Weblate employs a wide range of quality checks on strings. The following section describes them all in further detail. There are also language specific checks. Please file a bug if anything is reported in error.

See also

CHECK_LIST, Customizing behavior

Translation checks¶

Executed upon every translation change, helping translators maintain good quality translations.

Unchanged translation¶

Happens if the source and corresponding translation strings is identical, down to at least one of the plural forms. Some strings commonly found across all languages are ignored, and various markup is stripped. This reduces the number of false positives.

This check can help find strings mistakenly untranslated.

The default behavior of this check is to exclude words from the built-in blacklist from the checking. These are words which are frequently not being translated. This is useful to avoid false positives on short strings, which consist only of single word which is same in several languages. This blacklist can be disabled by adding strict-same flag to string or component.

Starting or trailing newline¶

Source and translation do not both start (or end) with a newline.

Newlines usually appear in source strings for good reason, omissions or additions can lead to formatting problems when the translated text is put to use.

Starting spaces¶

Source and translation do not both start with the same number of spaces.

A space in the beginning of a string is usually used for indentation in the interface and thus important to keep.

Trailing space¶

Checks that trailing spaces are replicated between both source and translation.

Trailing space is usually utilized to space out neighbouring elements, so removing it might break layout.

Double space¶

Checks that double space is present in translation to avoid false positives on other space-related checks.

Check is false when double space is found in source meaning double space is intentional.

Trailing stop¶

Checks that full stops are replicated between both source and translation. The presence of full stops is checked for various languages where they do not belong (Chinese, Japanese, Devanagari or Urdu).

See also

Full stop on Wikipedia

Trailing colon¶

Checks that colons are replicated between both source and translation. The presence of colons is also checked for various languages where they do not belong (Chinese or Japanese).

See also

Colon on Wikipedia

Trailing question mark¶

Checks that question marks are replicated between both source and translation. The presence of question marks is also checked for various languages where they do not belong (Armenian, Arabic, Chinese, Korean, Japanese, Ethiopic, Vai or Coptic).

See also

Question mark on Wikipedia

Trailing exclamation¶

Checks that exclamations are replicated between both source and translation. The presence of exclamation marks is also checked for various languages where they do not belong (Chinese, Japanese, Korean, Armenian, Limbu, Myanmar or Nko).

See also

Exclamation mark on Wikipedia

Punctuation spacing¶

New in version 3.9.

Checks that there is non breakable space before double punctuation sign (exclamation mark, question mark, semicolon and colon). This rule is used only in a few selected languages like French or Breton, where space before double punctuation sign is a typographic rule.

See also

French and English spacing on Wikipedia

Trailing ellipsis¶

Checks that trailing ellipses are replicated between both source and translation. This only checks for real ellipsis (…) not for three dots (...).

An ellipsis is usually rendered nicer than three dots in print, and sounds better with text-to-speech.

See also

Ellipsis on Wikipedia

Trailing semicolon¶

Checks that semicolons at the end of sentences are replicated between both source and translation. This can be useful to keep formatting of entries such as desktop files.

See also

Semicolon on Wikipedia

Maximum length¶

Checks that translations are of acceptable length to fit available space. This only checks for the length of translation characters.

Unlike the other checks, the flag should be set as a key:value pair like max-length:100.

Formatted strings¶

Checks that formatting in strings are replicated between both source and translation. Omitting format strings in translation usually causes severe problems, so the formatting in strings should usually match the source.

Weblate supports checking format strings in several languages. The check is not enabled automatically, only if a string is flagged appropriately (e.g. c-format for C format). Gettext adds this automatically, but you will probably have to add it manually for other file formats or if your PO files are not generated by xgettext.

This can be done per unit (see Additional info on source strings) or in Component configuration. Having it defined per component is simpler, but can lead to false positives in case the string is not interpreted as a formating string, but format string syntax happens to be used.

Besides checking, this will also highligh the formatting strings to easily insert them into translated strings:

Python format¶

Simple format string	`There are %d apples`
Named format string	`Your balance is %(amount) %(currency)`
Flag to enable	python-format

Python brace format¶

Simple format string	`There are {} apples`
Named format string	`Your balance is {amount} {currency}`
Flag to enable	python-brace-format

PHP format¶

Simple format string	`There are %d apples`
Position format string	`Your balance is %1$d %2$s`
Flag to enable	php-format

C format¶

Simple format string	`There are %d apples`
Position format string	`Your balance is %1$d %2$s`
Flag to enable	c-format

See also

C format strings, C printf format

Perl format¶

Simple format string	`There are %d apples`
Position format string	`Your balance is %1$d %2$s`
Flag to enable	perl-format

See also

Perl sprintf, Perl Format Strings

JavaScript format¶

Simple format string	`There are %d apples`
Flag to enable	javascript-format

See also

JavaScript formatting strings

AngularJS interpolation string¶

Named format string	`Your balance is {{amount}} {{ currency }}`
Flag to enable	angularjs-format

See also

AngularJS: API: $interpolate

C# format¶

Position format string	`There are {0} apples`
Flag to enable	c-sharp-format

See also

C# String Format

i18next interpolation¶

New in version 4.0.

Interpolation	`There are {{number}} apples`
Nesting	`There are $t(number) apples`
Flag to enable	i18next-interpolation

See also

i18next interpolation

Java format¶

Simple format string	`There are %d apples`
Position format string	`Your balance is %1$d %2$s`
Flag to enable	java-format

See also

Java Format Strings

Java MessageFormat¶

Position format string	`There are {0} apples`
Flag to enable	java-messageformat enables the check unconditionally
	auto-java-messageformat enables check only if there is a format string in the source

See also

Java MessageFormat

Qt format¶

Position format string	`There are %1 apples`
Plural format string	`There are %Ln apple(s)`
Flag to enable	qt-format, qt-plural-format

See also

Qt QString::arg(), Qt i18n guide

Percent placeholders¶

New in version 4.0.

Simple format string	`There are %number% apples`
Flag to enable	percent-placeholders

Ruby format¶

Simple format string	`There are %d apples`
Position format string	`Your balance is %1$f %2$s`
Named format string	`Your balance is %+.2<amount>f %<currency>s`
Named template string	`Your balance is %{amount} %{currency}`
Flag to enable	ruby-format

See also

Ruby Kernel#sprintf

Placeholders¶

New in version 3.9.

Translation is missing some placeholders. These are either extracted from the translation file or defined manually using placeholders flag, more can be separated with colon:

placeholders:$URL$:$TARGET$

Regular expression¶

New in version 3.9.

Translation does not match regular expression. The expression is either extracted from the translation file or defined manually using regex flag:

regex:^foo|bar$

Missing plurals¶

Checks that all plural forms of a source string have been translated. Specifics on how each plural form is used can be found in the string definition.

Failing to fill in plural forms will in some cases lead to displaying nothing when the plural form is in use.

Same plurals¶

Check that fails if some plural forms are duplicated in the translation. In most languages they have to be different.

Inconsistent¶

Weblate checks translations of the same string across all translation within a project to help you keep consistent translations.

The check fails on differing translations of one string within a project. This can also lead to inconsistencies in displayed checks. You can find other translations of this string on the Other occurences tab.

Note

This check also fires in case the string is translated in one component and not in another. It can be used as a quick way to manually handle strings which are not translated in some components just by clicking on the Use this string button displayed on each line in the Other occurences tab.

You can use Automatic translation addon to automate translating of newly added strings which are already translated in another component.

Has been translated¶

Means a string has been translated already. This can happen when the translations have been reverted in VCS or lost otherwise.

Mismatched \n¶

Usually escaped newlines are important for formatting program output. Check fails if the number of \\n literals in translation do not match the source.

Mismatched n¶

Usually newlines are important for formatting program output. Check fails if the number of \n literals in translation do not match the source.

BBcode markup¶

BBCode represents simple markup, like for example highlighting important parts of a message in bold font, or italics.

This check ensures they are also found in translation.

Note

The method for detecting BBcode is currently quite simple so this check might produce false positives.

Zero-width space¶

Zero-width space (<U+200B>) characters are used to break messages within words (word wrapping).

As they are usually inserted by mistake, this check is triggered once they are present in translation. Some programs might have problems when this character is used.

See also

Zero width space on Wikipedia

XML syntax¶

New in version 2.8.

The XML markup is not valid.

XML markup¶

This usually means the resulting output will look different. In most cases this is not a desired result from changing the translation, but occasionally it is.

Checks that XML tags are replicated between both source and translation.

Unsafe HTML¶

New in version 3.9.

The translation uses unsafe HTML markup. This check has to be enabled using safe-html flag (see Customizing behavior). There is also accompanied autofixer which can automatically sanitize the markup.

See also

The HTML check is performed by the Bleach library developed by Mozilla.

Markdown references¶

New in version 3.5.

Markdown link references do not match source.

See also

Markdown links

Markdown links¶

New in version 3.5.

Markdown links do not match source.

See also

Markdown links

Markdown syntax¶

New in version 3.5.

Markdown syntax does not match source

See also

Markdown span elements

Kashida letter used¶

New in version 3.5.

The decorative Kashida letters should not be used in translation. These are also known as Tatweel.

See also

Kashida on Wikipedia

URL¶

New in version 3.5.

The translation does not contain an URL. This is triggered only in case the unit is marked as containing URL. In that case the translation has to be a valid URL.

Maximum size of translation¶

New in version 3.7.

Translation rendered text should not exceed given size. It renders the text with line wrapping and checks if it fits into given boundaries.

This check needs one or two parameters - maximal width and maximal number of lines. In case the number of lines is not provided, one line text is considered.

You can also configure used font by font-* directives (see Customizing behavior), for example following translation flags say that the text rendered with ubuntu font size 22 should fit into two lines and 500 pixels:

max-size:500:2, font-family:ubuntu, font-size:22

Hint

You might want to set font-* directives in Component configuration to have the same font configured for all strings within a component. You can override those values per string in case you need to customize it per string.

See also

Managing fonts, Customizing behavior

Source checks¶

Source checks can help developers improve the quality of source strings.

Unpluralised¶

The string is used as a plural, but does not use plural forms. In case your translation system supports this, you should use the plural aware variant of it.

For example with Gettext in Python it could be:

from gettext import ngettext

print ngettext('Selected %d file', 'Selected %d files', files) % files

Ellipsis¶

This fails when the string uses three dots (...) when it should use an ellipsis character (…).

Using the Unicode character is in most cases the better approach and looks better rendered, and may sound better with text-to-speech.

See also

Ellipsis on Wikipedia

Multiple failing checks¶

Numerous translations of this string have failing quality checks. This is usually an indication that something could be done to improve the source string.

This check failing can quite often be caused by a missing full stop at the end of a sentence, or similar minor issues which translators tend to fix in translation, while it would be better to fix it in the source string.

Searching¶

New in version 3.9.

Advanced queries using boolean operations, parentheses, or field specific lookup can be used to find the strings you want.

When not defining any field, the lookup happens on Source, Target and Context fields.

Simple search¶

Any phrase typed into the search box is split into words. Strings containing any of them are are shown. To look for an exact phrase, put “the searchphrase” into quotes (both single (‘) and double (“) quotes will work).

Fields¶

source:TEXT: Source string case insensitive search.
target:TEXT: Target string case insensitive search.
context:TEXT: Context string case insensitive search.
note:TEXT: Comment string case insensitive search.
location:TEXT: Location string case insensitive search.
priority:NUMBER: String priority.
added:DATETIME: Timestamp when string was added to Weblate.
state:TEXT: State search (approved, translated, needs-editing, empty, read-only), supports Field operators.
pending:BOOLEAN: String pending for flushing to VCS.
has:TEXT: Search for string having attributes (plural, context, suggestion, comment, check, ignored-check, translation, shaping).
is:TEXT: Search for string states (pending, translated, untranslated).
language:TEXT: String target language.
changed_by:TEXT: String was changed by author with given username.
changed:DATETIME: String was changed on date, supports Field operators.
check:TEXT: String has failing check.
ignored_check:TEXT: String has ignored check.
comment:TEXT: Search in user comments.
comment_author:TEXT: Filter by comment author.
suggestion:TEXT: Search in suggestions.
suggestion_author:TEXT: Filter by suggestion author.

Boolean operators¶

You can combine lookups using AND, OR, NOT and parentheses to form complex queries. For example: state:translated AND (source:hello OR source:bar)

Field operators¶

You can specify operators, ranges or partial lookups for date or numeric searches:

state:>=translated: State is translated or better (approved).
changed:2019: Changed in year 2019.
changed:[2019-03-01 to 2019-04-01]: Changed between two given dates.

Exact operators¶

You can do an exact match query on different string fields using = operator. For example, to search for all source strings exactly matching hello world, use: source:="hello world". For searching single word expressions, you can skip quotes. For example, to search for all source strings matching hello, you can use: source:=hello.

Regular expressions¶

Anywhere text is accepted you can also specify a regular expression as r"regexp". For instance, to search for all source strings which contain any digit between 2 and 5, use: source:r"[2-5]"

Application developer guide¶

Using Weblate is a process that brings your users closer to you, by bringing you closer to your translators. It up to you to decide how many of its features you want to make use of.

Starting with internationalization¶

You have a project and want to to translate it into several languages? This guide will help you to do so. We will showcase several typical situations, but most of the examples are generic and can be applied to other scenarios as well.

Before translating any software, you should realize that languages around the world are really different and you should not make any assumption based on your experience. For most of languages it will look weird if you try to concatenate a sentence out of translated segments. You also should properly handle plural forms because many languages have complex rules for that and the internationalization framework you end up using should support this.

Last but not least, sometimes it might be necessary to add some context to the translated string. Imagine a translator would get string Sun to translate. Without context most people would translate that as our closest star, but it might be actually used as an abbreviation for Sunday.

Choosing internationalization framework¶

Choose whatever is standard on your platform, try to avoid reinventing the wheel by creating your own framework to handle localizations. Weblate supports most of the widely used frameworks, see Supported file formats for more information (especially Translation types capabilities).

Our personal recommendation for some plaforms is in the following table. This is based on our experience, but that can not cover all use cases, so always consider your environment when doing the choice.

Platform	Recommended format
Android	Android string resources
iOS	Apple iOS strings
Qt	Qt Linguist .ts
Python	GNU gettext
PHP	GNU gettext [1]
C/C++	GNU gettext
C#	.XML resource files
Perl	GNU gettext
Ruby	Ruby YAML files
Web extensions	WebExtension JSON
Java	XLIFF [2]
JavaScript	JSON i18next files [3]

[1]	The native Gettext support in PHP is buggy and often missing on Windows builds, it is recommended to use third party library motranslator instead.

[2]	You can also use Java properties if plurals are not needed.

[3]	You can also use plain JSON files if plurals are not needed.

Following chapters describe two use cases - GNU Gettext and Sphinx, but many of the steps are quite generic and apply to the other frameworks as well.

Translating software using GNU Gettext¶

GNU Gettext is one of the most widely used tool for internationalization of free software. It provides a simple yet flexible way to localize the software. It has great support for plurals, it can add further context to the translated string and there are quite a lot of tools built around it. Of course it has great support in Weblate (see GNU gettext file format description).

Note

If you are about to use it in proprietary software, please consult licensing first, it might not be suitable for you.

GNU Gettext can be used from a variety of languages (C, Python, PHP, Ruby, JavaScript and many more) and usually the UI frameworks already come with some support for it. The standard usage is through the gettext() function call, which is often aliased to _() to make the code simpler and easier to read.

Additionally it provides pgettext() call to provide additional context to translators and ngettext() which can handle plural types as defined for target language.

As a widely spread tool, it has many wrappers which make its usage really simple, instead of manual invoking of Gettext described below, you might want to try one of them, for example intltool.

Sample program¶

The simple program in C using Gettext might look like following:

#include <libintl.h>
#include <locale.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    int count = 1;
    setlocale(LC_ALL, "");
    bindtextdomain("hello", "/usr/share/locale");
    textdomain("hello");
    printf(
        ngettext(
            "Orangutan has %d banana.\n",
            "Orangutan has %d bananas.\n",
            count
        ),
        count
    );
    printf("%s\n", gettext("Thank you for using Weblate."));
    exit(0);
}

Extracting translatable strings¶

Once you have code using the gettext calls, you can use xgettext to extract messages from it and store them into a .pot:

$ xgettext main.c -o po/hello.pot

Note

There are alternative programs to extract strings from the code, for example pybabel.

This creates a template file, which you can use for starting new translations (using msginit) or updating existing ones after code change (you would use msgmerge for that). The resulting file is simply a structured text file:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-10-23 11:02+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"

#: main.c:14
#, c-format
msgid "Orangutan has %d banana.\n"
msgid_plural "Orangutan has %d bananas.\n"
msgstr[0] ""
msgstr[1] ""

#: main.c:20
msgid "Thank you for using Weblate."
msgstr ""

Each msgid line defines a string to translate, the special empty string in the beginning is the file header containing metadata about the translation.

Starting new translation¶

With the template in place, we can start our first translation:

$ msginit -i po/hello.pot -l cs --no-translator -o po/cs.po
Created cs.po.

The just created cs.po already has some information filled in. Most importantly it got the proper plural forms definition for chosen language and you can see number of plurals have changed according to that:

# Czech translations for PACKAGE package.
# Copyright (C) 2015 THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# Automatically generated, 2015.
#
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-10-23 11:02+0200\n"
"PO-Revision-Date: 2015-10-23 11:02+0200\n"
"Last-Translator: Automatically generated\n"
"Language-Team: none\n"
"Language: cs\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=ASCII\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;\n"

#: main.c:14
#, c-format
msgid "Orangutan has %d banana.\n"
msgid_plural "Orangutan has %d bananas.\n"
msgstr[0] ""
msgstr[1] ""
msgstr[2] ""

#: main.c:20
msgid "Thank you for using Weblate."
msgstr ""

This file is compiled into an optimized binary form, the .mo file used by the GNU Gettext functions at runtime.

Updating strings¶

Once you add more strings or change some strings in your program, you execute again xgettext which regenerates the template file:

$ xgettext main.c -o po/hello.pot

Then you can update individual translation files to match newly created templates (this includes reordering the strings to match new template):

$ msgmerge --previous --update po/cs.po po/hello.pot

Importing to Weblate¶

To import such translation into Weblate, all you need to define are the following fields when creating component (see Component configuration for detailed description of the fields):

Field	Value
Source code repository	URL of the VCS repository with your project
File mask	`po/*.po`
Template for new translations	`po/hello.pot`
File format	Choose Gettext PO file
New language	Choose Create new language file

And that’s it, you’re now ready to start translating your software!

See also

You can find a Gettext example with many languages in the Weblate Hello project on GitHub: <https://github.com/WeblateOrg/hello>.

Translating documentation using Sphinx¶

Sphinx is a tool for creating beautiful documentation. It uses simple reStructuredText syntax and can generate output in many formats. If you’re looking for an example, this documentation is also built using it. The very useful companion for using Sphinx is the Read the Docs service, which will build and publish your documentation for free.

I will not focus on writing documentation itself, if you need guidance with that, just follow instructions on the Sphinx website. Once you have documentation ready, translating it is quite easy as Sphinx comes with support for this and it is quite nicely covered in their Internationalization. It’s matter of few configuration directives and invoking of the sphinx-intl tool.

If you are using Read the Docs service, you can start building translated documentation on the Read the Docs. Their Localization of Documentation covers pretty much everything you need - creating another project, set its language and link it from master project as a translation.

Now all you need is translating the documentation content. As Sphinx splits the translation files per source file, you might end up with dozen of files, which might be challenging to import using the Weblate’s web interface. For that reason, there is the import_project management command.

Depending on exact setup, importing of the translation might look like:

$ weblate import_project --name-template 'Documentation: %s' \
    --file-format po \
    project https://github.com/project/docs.git master \
    'docs/locale/*/LC_MESSAGES/**.po'

If you have more complex document structure, importing different folders is not directly supported; you currently have to list them separately:

$ weblate import_project --name-template 'Directory 1: %s' \
    --file-format po \
    project https://github.com/project/docs.git master \
    'docs/locale/*/LC_MESSAGES/dir1/**.po'
$ weblate import_project --name-template 'Directory 2: %s' \
    --file-format po \
    project https://github.com/project/docs.git master \
    'docs/locale/*/LC_MESSAGES/dir2/**.po'

See also

The Odorik python module documentation is built using Sphinx, Read the Docs and translated using Weblate.

Integrating with Weblate¶

Getting translations updates from Weblate¶

To fetch updated strings from Weblate you can simply fetch the underlying repository (either from filesystem or it can be made available through Git exporter). Prior to this, you might want to commit any pending changes (see Lazy commits). This can be achieved in the user interface (in the Repository maintenance) or from command line using Weblate Client.

This can be automated if you grant Weblate push access to your repository and configure Push URL in the Component configuration.

See also

Continuous localization

Pushing string changes to Weblate¶

To push newly updated strings to Weblate, just let it pull from the upstream repository. This can be achieved in the user interface (in the Repository maintenance) or from command line using Weblate Client.

This can be automated by installing a webhook on your repository to trigger Weblate whenever there is a new commit, see Updating repositories for more details.

See also

Continuous localization

Translation component alerts¶

Shows errors in the Weblate configuration or the translation project for any given translation component. Guidance on how to address found issues is also offered.

Currently the following is covered:

Duplicated source strings in translation files
Duplicated languages within translations
Merge or update failures in the source repository
Unused new base in component settings
Parse errors in the translation files
Duplicate filemask used for linked components

Alerts are listed on each respective component page as Alerts. If it is missing, the component clears all current checks. Alerts can not be ignored, but will disappear once the underlying problem has been fixed.

A component with both duplicated strings and languages looks like this:

Building translators community¶

Localization guide¶

New in version 3.9.

The Localization guide which can be found in the Insights menu of each component can give you guidance to make your localization process easy for translators.

Managing translations¶

Adding new translations¶

New strings can be made available for translation when they appear in the base file, called Template for new translations (see Component configuration). If your file format doesn’t require such a file, as is the case with most monolingual translation flows, you can start with blank files).

New languages can be added right away when requested by a user in Weblate, or a notification will be sent to project admins for approval and manual addition. This can be done using Start new translation in Component configuration.

Note

Project admins can always start translation within Weblate directly.

Language files added manually to the VCS are added to the component when Weblate updates the repository. About repository update settings, see Updating repositories).

String shapings¶

Shapings are useful to group several strings together so that translators can see all variants of the string at one place. You can define regular expression to group the strings in the Component configuration:

The expression is matched against Context to generate root key of the shaping. All matching strings are then part of single shapings group, including the translation exactly matching the root key, even if that is not matched by the regular expression.

The following table lists some usage examples:

Use case	Regular expression shaping	Matched translation keys
Suffix identification	`(Short\|Min)$`	`monthShort`, `monthMin`, `month`
Inline identification	`#[SML]`	`dial#S.key`, `dial#M.key`, `dial.key`

The shaping is later grouped when translating:

String labels¶

Split component translation strings into categories by text and colour in the project configuration.

Hint

Labels can be assigned to units in Additional info on source strings by bulk editing, or using the Bulk edit addon.

Reviewing strings¶

Activity reports¶

Activity reports check changes of translations, for projects, components or individual users.

The activity reports for a project or component is accessible from its dashboard, on the Insights tab, selecting Activity.

More reports are accessible on the Insights tab, selecting Translation reports.

The activity of the currently signed in user can be seen by clicking on Profile from the user menu on the top right.

Source strings checks¶

There are many Quality checks, some of them focus on improving the quality of source strings. Many failing checks suggest a hint to make source strings easier to translate. All types of failing source checks are displayed on the Source tab of every component.

Translation string checks¶

Erroneous failing translation string checks indicate the problem is with the source string. Translators sometimes fix mistakes in the translation instead of reporting it - a typical example is a missing full stop at the end of a sentence.

Reviewing all failing checks can provide valuable feedback to improve its source strings. To make source strings review easier, Weblate automatically creates a translation for the source language and shows you source level checks there:

One of the most interesting checks here is the Multiple failing checks - it is triggered whenever there is failure on multiple translations of a given string. Usually this is something to look for, as this is a string which translators have problems translating properly.

The detailed listing is a per language overview:

String comments¶

Translators can comment on both translation and source strings. Each Component configuration can be configured to receive such comments to an e-mail address, and using the developers mailing list is usually the best approach. This way you can keep an eye on when problems arise in translation, take care of them, and fix them quickly.

Promoting the translation¶

Weblate provides you widgets to share on your website or other sources to promote the translation project. It also has a nice welcome page for new contributors to give them basic information about the translation. Additionally you can share information about translation using Facebook or Twitter. All these possibilities can be found on the Share tab:

All these badges are provided with the link to simple page which explains users how to translate using Weblate:

Translation progress reporting¶

Reporting features give insight into how a translation progresses over a given period. A summary of contributions to any given component over time is provided. The reporting tool is found in the Insights menu of any translation component, project or on the dashboard:

Several reporting tools are available on this page and all can produce output in HTML, reStructuredText or JSON. The first two formats are suitable for embedding statistics into existing documentation, while JSON is useful for further processing of the data.

Translator credits¶

Generates a document usable for crediting translators - sorted by language and lists all contributors to a given language:

* Czech

    * Michal Čihař <michal@cihar.com>
    * John Doe <john@example.com>

* Dutch

    * Jane Doe <jane@example.com>

It will render as:

Czech

Michal Čihař <michal@cihar.com>

John Doe <john@example.com>

Dutch

Jae Doe <jane@example.com>

Contributor stats¶

Generates the number of translated words and strings by translator name:

======================================== ======================================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ========================
Name                                     Email                                    Count total              Source words total       Source chars total       Target words total       Target chars total       Count new                Source words new         Source chars new         Target words new         Target chars new         Count approved           Source words approved    Source chars approved    Target words approved    Target chars approved    Count edited             Source words edited      Source chars edited      Target words edited      Target chars edited
======================================== ======================================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ========================
Michal Čihař                             michal@cihar.com                                                1                        3                       24                        3                       21                        1                        3                       24                        3                       21                        0                        0                        0                        0                        0                        0                        0                        0                        0                        0
Allan Nordhøy                            allan@example.com                                               2                        5                       25                        4                       28                        2                        3                       24                        3                       21                        0                        0                        0                        0                        0                        0                        0                        0                        0                        0
======================================== ======================================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ======================== ========================

And it will get rendered as:

Name	Email	Count total	Source words total	Source chars total	Target words total	Target chars total	Count new	Source words new	Source chars new	Target words new	Target chars new	Count approved	Source words approved	Source chars approved	Target words approved	Target chars approved	Count edited	Source words edited	Source chars edited	Target words edited	Target chars edited
Michal Čihař	michal@cihar.com	1	3	24	3	21	1	3	24	3	21	0	0	0	0	0	0	0	0	0	0
Allan Nordhøy	allan@example.com	2	5	25	4	28	2	3	24	3	21	0	0	0	0	0	0	0	0	0	0

It can be useful if you pay your translators based on amount of work, it gives you various stats on translators work.

All stats are available in three variants:

Total: Overall number of edited strings.
New: Newly translated strings which didn’t have translation before.
Approved: Count for string approvals in review workflow (see Dedicated reviewers).
Edited: Edited strings which had translation before.

The following metrics are available for each:

Count: Number of strings.
Edits: Number of edits in the string, measured in Damerau–Levenshtein distance.
Source words: Number of words in the source string.
Source characters: Number of characters in the source string.
Target words: Number of words in the translated string.
Target characters: Number of characters in the translated string.

Translation workflows¶

Several translation workflows are supported.

The following is not a complete list of ways to configure Weblate. You can base other workflows on the most usual examples listed here.

Translation access¶

The Access control is not much discussed in the workflows as each access control option can be applied to any workflow. Please consult that documentation for information on how to manage access to translations.

In the following chapters, any user means a user who has access to the translation. It can be any authenticated user if the project is public, or a user that has a Translate permission for the project.

Translation states¶

Each translated string can be in one of following states:

Untranslated: Translation is empty, it might or not be stored in the file, depending on the file format.
Needs editing: Translation needs editing, this is usually the result of a source string change. The translation is stored in the file, depending on the file format it might be marked as needing edit (for example as it gets a fuzzy flag).
Waiting for review: Translation is made, but not reviewed. It is stored in the file as a valid translation.
Approved: Translation has been approved in the review. It can no longer be changed by translators, but only by reviewers. Translators can only add suggestions to it.
Suggestions: Suggestions are stored in Weblate only and not in the translation file.

Direct translation¶

This is most usual setup for smaller teams, anybody can directly translate. This is also the default setup in Weblate.

Any user can edit translations.
Suggestions are optional ways to suggest changes, when translators are not sure about the change.

Setting	Value	Note
Enable reviews	Off	Configured at project level.
Enable suggestions	On	It is useful for users to be able to suggest when they are not sure.
Suggestion voting	Off
Autoaccept suggestions	0
Translators group	Users	Or Translate with access control.
Reviewers group	N/A	Not used.

Peer review¶

With this workflow, anybody can add suggestions, and need approval from additional member(s) before it is accepted as a translation.

Any user can add suggestions.
Any user can vote for suggestions.
Suggestions become translations when given a predetermined number of votes.

Setting	Value	Note
Enable reviews	off	Configured at project level.
Enable suggestions	on
Suggestion voting	on
Autoaccept suggestions	1	You can set higher value to require more peer reviews.
Translators group	Users	Or Translate with access control.
Reviewers group	N/A	Not used, all translators review.

Dedicated reviewers¶

New in version 2.18: The proper review workflow is supported since Weblate 2.18.

With dedicated reviewers you have two groups of users, one able to submit translations, and one able to review them to ensure translations are consistent and that the quality is good.

Any user can edit unapproved translations.
Reviewer can approve / unapproved strings.
Reviewer can edit all translations (including approved ones).
Suggestions can also be used to suggest changes for approved strings.

Setting	Value	Note
Enable reviews	on	Configured at project level.
Enable suggestions	off	It is useful for users to be able to suggest when they are not sure.
Suggestion voting	off
Autoaccept suggestions	0
Translators group	Users	Or Translate with access control.
Reviewers group	Reviewers	Or Review with access control.

Turning on reviews¶

Reviews can be turned on in the project configuration, from the Workflow subpage of project settings (to be found in the Manage → Settings menu):

Note

Depending on Weblate configuration, the setting might not be available to you. For example on Hosted Weblate this is not available for projects hosted for free.

Source strings reviews¶

With Enable source reviews enabled, the review process can be applied on the source strings. Once enabled, users can report issues in the source strings. The actual process depends on whether you use bilingual or monolingual formats.

For monolingual formats, the source string review behaves similarly as with Dedicated reviewers - once issue is reported on the source string, it is marked as Needs editing.

The bilingual formats do not allow direct editing of the source strings (these are typically extracted directly from the source code). In this case Source needs review label is attached to strings reported by translators. You should review such strings and either edit them in the source or remove the label.

Frequently Asked Questions¶

Configuration¶

How to create an automated workflow?¶

Weblate can handle all the translation things semi-automatically for you. If you give it push access to your repository, the translations can happen without interaction, unless some merge conflict occurs.

Set up your Git repository to tell Weblate when there is any change, see Notification hooks for info on how to do it.
Set a push URL at your Component configuration in Weblate, this allows Weblate to push changes to your repository.
Turn on push-on-commit on your Project configuration in Weblate, this will make Weblate push changes to your repository whenever they happen at Weblate.

How to access repositories over SSH?¶

Please see Accessing repositories for info on setting up SSH keys.

How to fix merge conflicts in translations?¶

Merge conflicts happen from time to time when the translation file is changed in both Weblate and the upstream repository concurrently. You can usually avoid this by merging Weblate translations prior to making changes in the translation files (e.g. before running msgmerge). Just tell Weblate to commit all pending translations (you can do it in Repository maintenance in the Manage menu) and merge the repository (if automatic push is not on).

If you’ve already ran into a merge conflict, the easiest way is to solve all conflicts locally at your workstation - is to simply add Weblate as a remote repository, merge it into upstream and fix any conflicts. Once you push changes back, Weblate will be able to use the merged version without any other special actions.

Note

Depending on your setup, access to the Weblte repository might require authentication. When using the built in Git exporter in Weblate, you authenticate with your username and the API key.

# Commit all pending changes in Weblate, you can do this in the UI as well:
wlc commit
# Lock the translation in Weblate, again this can be done in the UI as well:
wlc lock
# Add Weblate as remote:
git remote add weblate https://hosted.weblate.org/git/project/component/
# You might need to include credentials in some cases:
git remote add weblate https://username:APIKEY@hosted.weblate.org/git/project/component/

# Update weblate remote:
git remote update weblate

# Merge Weblate changes:
git merge weblate/master

# Resolve conflicts:
edit …
git add …
…
git commit

# Push changes to upstream repository, Weblate will fetch merge from there:
git push

# Open Weblate for translation:
wlc unlock

If you’re using multiple branches in Weblate, you can do the same to all of them:

# Add and update Weblate remotes
git remote add weblate-one https://hosted.weblate.org/git/project/one/
git remote add weblate-second https://hosted.weblate.org/git/project/second/
git remote update weblate-one weblate-second

# Merge QA_4_7 branch:
git checkout QA_4_7
git merge weblate-one/QA_4_7
... # Resolve conflicts
git commit

# Merge master branch:
git checkout master
git merge weblates-second/master
... # Resolve conflicts
git commit

# Push changes to the upstream repository, Weblate will fetch the merge from there:
git push

In case of gettext PO files, there is a way to merge conflicts in a semi-automatic way:

Fetch and keep a local clone of the Weblate Git repository. Also get a second fresh local clone of the upstream Git repository (i. e. you need two copies of the upstream Git repository: An intact and a working copy):

# Add remote:
git remote add weblate /path/to/weblate/snapshot/

# Update Weblate remote:
git remote update weblate

# Merge Weblate changes:
git merge weblate/master

# Resolve conflicts in the PO files:
for PO in `find . -name '*.po'` ; do
    msgcat --use-first /path/to/weblate/snapshot/$PO\
               /path/to/upstream/snapshot/$PO -o $PO.merge
    msgmerge --previous --lang=${PO%.po} $PO.merge domain.pot -o $PO
    rm $PO.merge
    git add $PO
done
git commit

# Push changes to the upstream repository, Weblate will fetch merge from there:
git push

How do I translate several branches at once?¶

Weblate supports pushing translation changes within one Project configuration. For every Component configuration which has it turned on (the default behavior), the change made is automatically propagated to others. This way translations are kept synchronized even if the branches themselves have already diverged quite a lot, and it is not possible to simply merge translation changes between them.

Once you merge changes from Weblate, you might have to merge these branches (depending on your development workflow) discarding differences:

git merge -s ours origin/maintenance

How to translate multi-platform projects?¶

Weblate supports a wide range of file formats (see Supported file formats) and the easiest approach is to use the native format for each platform.

Once you have added all platform translation files as components in one project (see Adding translation projects and components), you can utilize the translation propagation feature (turned on by default, and can be turned off in the Component configuration) to translate strings for all platforms at once.

How to export the Git repository that Weblate uses?¶

There is nothing special about the repository, it lives under the DATA_DIR directory and is named vcs/<project>/<component>/. If you have SSH access to this machine, you can use the repository directly.

For anonymous access, you might want to run a Git server and let it serve the repository to the outside world.

Alternatively, you can use Git exporter inside Weblate to automate this.

What are the options for pushing changes back upstream?¶

This heavily depends on your setup, Weblate is quite flexible in this area. Here are examples of some workflows used with Weblate:

Weblate automatically pushes and merges changes (see How to create an automated workflow?).
You manually tell Weblate to push (it needs push access to the upstream repository).
Somebody manually merges changes from the Weblate git repository into the upstream repository.
Somebody rewrites history produced by Weblate (e.g. by eliminating merge commits), merges changes, and tells Weblate to reset the content in the upstream repository.

Of course you are free to mix all of these as you wish.

How can I limit Weblate access to only translations, without exposing source code to it?¶

You can use git submodule for separating translations from source code while still having them under version control.

Create a repository with your translation files.

Add this as a submodule to your code:

git submodule add git@example.com:project-translations.git path/to/translations

Link Weblate to this repository, it no longer needs access to the repository containing your source code.
You can update the main repository with translations from Weblate by:
```
git submodule update --remote path/to/translations
```

Please consult the git submodule documentation for more details.

How can I check whether my Weblate is set up properly?¶

Weblate includes a set of configuration checks which you can see in the admin interface, just follow the Performance report link in the admin interface, or open the /manage/performance/ URL directly.

Why do links contain example.com as the domain?¶

Weblate uses Django’s sites framework and defines the sitename inside the database. You need to set the domain name to match your installation.

See also

Set correct site domain

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 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 that made the translation.

See also

Component configuration

Usage¶

How do I review the translations of others?¶

You can subscribe to any changes made in Notifications and then check others contributions as they come in by 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?¶

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 a compendium or a similar translation database.
You can set up tmserver with all databases you have and let Weblate use it. This is good when you want to use it several times during translation.
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 your way, please use a pre-commit hook for that.

For monolingual files (see Supported file formats) Weblate might add new translation strings not 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

Processing repository with scripts

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 info about plural forms or text direction.

You are free to define your own languages in the administrative interface, you just need to provide info 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

When accessing the site I get a “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 on your Weblate. For example:

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

See also

Allowed hosts setup

Features¶

Does Weblate support other VCSes 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 VCSes, Weblate requires using distributed VCS, and could probably be 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 the standard VCS tools you use for code.

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

See also

list_translators

Why does Weblate force showing 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 is great demand for this feature, it might be implemented in future versions.

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 still understands 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 translate-toolkit, however each format being slightly different, some issues with formats that are not well tested can arise.

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 additionally use whatever tools they are used to, and will more likely contribute to your project.

Bilingual and monolingual formats¶

Both monolingual and bilingual formats are supported. 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 the mapping of those to any given language (typically Android string resources). Some file formats are used in both variants, see the 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 paradigm.

Additionally this workflow can be extended by utilizing Intermediate language file to include strings provided by developers, but not to be used as is in the final strings.

Automatic detection¶

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

Translation types capabilities¶

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
.XML 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
Flat XML	mono	no	no	no	no	yes [10]
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 info about the string to translate.

[4]	Context is used to differentiate identical strings used in different scopes (for example Sun can be used as an abbreviated name of the day “Sunday” or as the name of our closest star).

[5]	Location of a string in source code might help proficient translators 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, 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, 5) The flags are extracted from the non-standard attibute `weblate-flags` for all XML based formats. Additionally `max-length:N` is supported through the `maxwidth` attribute as defined in the XLIFF standard, see Specifying translation flags.

GNU gettext¶

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

Contextual info stored in the file is supported by adjusting its headers or linking to corresponding source files.

The bilingual gettext PO file typically looks like this:

#: 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
Filemask	`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 the IDs in their source code and the string then needs to be translated to all languages, including English. This is supported, though you have to choose this file format explicitly when importing components into Weblate.

The monolingual gettext PO file typically looks like this:

#: 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
Filemask	`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.

XML Localization Interchange File Format (XLIFF) is usually used as bilingual, but Weblate supports it as monolingual as well.

See also

XML Localization Interchange File Format (XLIFF) specification

Translation states¶

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

The state attribute in the file is partially processed and mapped to the “Needs edit” state in Weblate (the following states are used to flag the string as needing edit if there is a 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.

If the translation string has approved="yes", it will also be imported into Weblate as “Approved”, anything else will be imported as “Waiting for review” (which matches the XLIFF specification).

While saving, Weblate doesn’t add those attributes unless necessary:

The state attribute is only added in case string is marked as needing edit.
The approved attribute is only added in case string has been reviewed.
In other cases the attributes are not added, but they are updated in case they are present.

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

See Dedicated reviewers.

Similarly upon importing such files (in the upload form), you should choose Import as translated under Processing of strings needing review.

Whitespace and newlines in XLIFF¶

Generally types or amounts of whitespace is not differentiated between in XML formats. 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) by using the weblate-flags attribute. Weblate also understands maxwidth and font attributes from the XLIFF specification:

<trans-unit id="10" maxwidth="100" size-unit="pixel" font="ubuntu;22;bold">
   <source>Hello %s</source>
</trans-unit>
<trans-unit id="20" maxwidth="100" size-unit="char" weblate-flags="c-format">
   <source>Hello %s</source>
</trans-unit>

The font attribute is parsed for font family, size and weight, the above example shows all of that, though only font family is required. Any whitespace in the font family is converted to underscore, so Source Sans Pro becomes Source_Sans_Pro, please keep that in mind when naming the font group (see Managing fonts).

Typical Weblate Component configuration for bilingual XLIFF
Filemask	`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

Java properties¶

Native Java format for translations.

Java properties are usually used as monolingual translations.

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

Note

Loading escape sequences works in UTF-8 mode as well, so please be careful choosing the correct enconding set to match your application needs.

Typical Weblate Component configuration
Filemask	`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 translations.

Typical Weblate Component configuration
Filemask	`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 translations.

Typical Weblate Component configuration when using as bilingual
Filemask	`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
Filemask	`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
Filemask	`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 your 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 be made available for translation.

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 translations.

Typical Weblate Component configuration
Filemask	`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 a base file with (what is most often the) 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
Filemask	`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 will not get corrupted before using Weblate in a production setup.

Following things are known to be broken:

Addition of new strings to a translation, every translation has to contain all strings (even if empty).
Handling of special characters 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 a base file with (what is most often the) 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 a file can look like:

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

Typical Weblate Component configuration
Filemask	`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 a base file with (what is most often the) English strings.

Note

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

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
Filemask	`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 Mozilla Firefox or Google Chromium.

Example file:

{
    "hello": {
        "message": "Ahoj světe!\n",
        "description": "Description",
        "placeholders": {
            "url" : {
              "content" : "$1",
              "example" : "https://developer.mozilla.org"
            }
        }
    },
    "orangutan": {
        "message": "",
        "description": "Description"
    },
    "try": {
        "message": "",
        "description": "Description"
    },
    "thanks": {
        "message": "",
        "description": "Description"
    }
}

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

.XML resource files¶

New in version 2.3.

A .XML resource (.resx) file employs a monolingual XML file format used in Microsoft .NET applications. It is [interchangeable with .resw, when using identical syntax to .resx](https://lingohub.com/developers/resource-files/resw-resx-localization).

Typical Weblate Component configuration
Filemask	`Resources/Language.*.resx`
Monolingual base language file	`Resources/Language.resx`
Template for new translations	Empty
File format	.XML 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 the recommended approach, as it is the 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 the dialect of the CSV file. In some cases the automatic detection might fail and you will get mixed results. This is especially true for CSV files with newlines in the values. As a workaround it is recommended to omit quoting characters.

Example file:

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

Typical Weblate Component configuration
Filemask	`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 of a YAML file:

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

Typical Weblate Component configuration
Filemask	`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
Filemask	`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
Filemask	`locale/*.dtd`
Monolingual base language file	`locale/en.dtd`
Template for new translations	Empty
File format	DTD file

See also

Mozilla DTD format

Flat XML files¶

New in version 3.9.

Example of a flat XML file:

<?xml version='1.0' encoding='UTF-8'?>
<root>
  <str key="hello_world">Hello World!</str>
  <str key="resource_key">Translated value.</str>
</root>

Typical Weblate Component configuration
Filemask	`locale/*.xml`
Monolingual base language file	`locale/en.xml`
Template for new translations	Empty
File format	Flat XML file

See also

Flat XML

Windows RC files¶

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

Warning

This format is still not supported on Python 3 due to bugs in underlying library, see <https://github.com/translate/translate/issues/3204>.

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
Filemask	`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.

Metadata used for publishing apps in various app stores can be translated. Currently the following tools are compatible:

The metadata consists of several textfiles, which Weblate will present as separate strings to translate.

Typical Weblate Component configuration
Filemask	`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 subtitle file (*.sub)
Advanced Substation Alpha subtitles file (*.ass)
Substation Alpha subtitle file (*.ssa)

Typical Weblate Component configuration
Filemask	`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.

Excel Open XML (.xlsx) files can be imported and exported.

When uploading XLSX files for translation, 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 called 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 an empty file and only translated strings to be included (for example Android string resources), while others expect to have all keys present (for example GNU gettext). In some situations this really doesn’t depend on the format, but rather on the framework you use to handle the translation (for example 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 the file format supports it, an 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: Only used in Android apps, produces language codes like pt-rBR.
Java style: User by Java—mostly BCP with legacy codes for Chinese.

Note

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

Read only strings¶

New in version 3.10.

Read-only strings from translation files will be included, but can not be edited in Weblate. This feature is natively supported by few formats (XLIFF and Android string resources), but can be emulated in others by adding a read-only flag, see Customizing behavior.

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 the correct URL (for example https://github.com/WeblateOrg/weblate.git), but for private repositories or for push URLs the setup is more complex and requires authentication.

Accessing repositories 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 appropriate permission to your repository (read only is okay for cloning, write is required for pushing). Depending on service and your organization settings, this happens immediately or requires confirmation from Weblate side. The invitations on GitHub are accepted automatically within five minutes, on other services manual processing is needed, so please be patient.

Once the weblate user is added, you can configure Source code repository and Repository push URL using SSH protocol (for example git@github.com:WeblateOrg/weblate.git).

SSH repositories¶

The most frequently used method to access private repositories is based on SSH. Authorize the public Weblate SSH key (see Weblate SSH key) to access the upstream repository this way.

Warning

On GitHub, each key can be added to only one repository, see GitHub repositories and Accessing repositories from Hosted Weblate.

Weblate also stores the host key fingerprint upon first connection, and fails to connect to the host should it be changed later (see Verifying SSH host keys).

In case adjustment is needed, do so from the Weblate admin interface:

Weblate SSH key¶

The Weblate public key is visible to all users browsing the About page.

Admins can generate or display the public key currently used by Weblate in the (from SSH keys) on the admin interface landing page.

Note

The corresponding private SSH key can not currently have a password, so make sure it is well protected.

Hint

Make a backup of the generated private Weblate SSH key.

Verifying SSH host keys¶

Weblate automatically remembers the SSH host keys on first access and remembers them for further use.

In case you want to verify them before connecting to the repository, verify the SSH host keys of the servers you are going to access in Add host key, from the same section of the admin interface. Enter the hostname you are going to access (e.g. gitlab.com), and press Submit. Verify its fingerprint matches the server you added. They are shown in the confirmation message:

GitHub repositories¶

Access via SSH is possible (see SSH repositories), but in case you need to access more than one repository, you will hit a GitHub limitation on allowed SSH key usage (since one key can be used only for one repository).

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

For bigger setups, it is usually better to create a dedicated user for Weblate, assign it the public SSH key generated in Weblate (see Weblate SSH key) and grant it access to all the repositories you want to translate. This approach is also used for Hosted Weblate, there is dedicated weblate user for that.

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 the referenced component, and the VCS repository will be stored just once on the disk.

HTTPS repositories¶

To access protected HTTPS repositories, include the username and password in the URL. Don’t worry, Weblate will strip this info when the URL is shown to users (if even allowed to see the repository URL at all).

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

Note

If you username or password contains special characters, 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, configure the VCS to use it.

This can be done using the http_proxy, https_proxy, and all_proxy environment variables, (as described in the cURL documentation) or by enforcing it in the VCS configuration, for example:

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

Note

The proxy configuration needs to be done under user running Weblate (see also Filesystem permissions) and with HOME=$DATA_DIR/home (see DATA_DIR), otherwise Git executed by Weblate will not use it.

Git¶

See also

See Accessing repositories for info on how to access different kinds of repositories.

Git with force push¶

This behaves exactly like Git itself, the only difference being that it always force pushes. This is intended only in the case of using a seperate repository for translations.

Warning

Use with caution, as this easily leads to lost commits in your upstream repository.

Customizing Git configuration¶

Weblate invokes all VCS commands with HOME=$DATA_DIR/home (see DATA_DIR), therefore editing the user configuration needs to be done in DATA_DIR/home/.git.

Git remote helpers¶

You can also use Git remote helpers for additionally supporting other version control systems, but be prepared to debug problems this may lead to.

At this time, helpers for Bazaar and Mercurial are available within separate repositories on GitHub: git-remote-hg and git-remote-bzr. Download them manually and put somewhere in your search path (for example ~/bin). Make sure you have the corresponding version control systems installed.

Once you have these installed, such remotes can be used to specify a repository in Weblate.

To clone the gnuhello project from Launchpad using Bazaar:

bzr::lp:gnuhello

For the hello repository from selenic.com using Mercurial:

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

Warning

The inconvenience of using Git remote helpers is for example with Mercurial, the remote helper sometimes creates a new tip when pushing changes back.

GitHub¶

New in version 2.3.

This adds a thin layer atop Git using the hub tool to allow pushing translation changes as pull requests, instead of pushing directly to the repository.

Git pushes changes directly to a repository, while GitHub creates pull requests. The latter is not needed for merely accessing Git repositories.

Pushing changes to GitHub as pull requests¶

If not wanting to push translations to a GitHub repository, they can be sent as either one or many pull requests instead.

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 requests requires a configured hub installation on your server. Follow the installation instructions at https://hub.github.com/ use hub to finish the configuration, for example:

# Use DATA_DIR as configured in Weblate settings.py, it is /app/data in the 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 in ~/.config/hub. This file has to be readable by the user running Weblate.

Note

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

GitLab¶

New in version 3.9.

This just adds a thin layer atop Git using the lab tool to allow pushing translation changes as merge requests instead of pushing directly to the repository.

There is no need to use this 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 GitLab creates merge request.

Pushing changes to GitLab as merge requests¶

If not wanting to push translations to a GitLab repository, they can be sent as either one or many merge requests instead.

Configure the lab command line tool and set GITLAB_USERNAME for this to work.

See also

GITLAB_USERNAME, Setting up Lab for configuration instructions

Setting up Lab¶

Pushing changes to GitLab as merge requests requires a configured lab installation on your server. Follow the installation instructions at lab and run it without any arguments to finish the configuration, for example:

# Use DATA_DIR as configured in Weblate settings.py, it is /app/data in the Docker
$ HOME=${DATA_DIR}/home lab
Enter GitLab host (default: https://gitlab.com):
Create a token here: https://gitlab.com/profile/personal_access_tokens
Enter default GitLab token (scope: api):
(Config is saved to ~/.config/lab.hcl)

The lab will ask you for your GitLab access token, retrieve it and store it in ~/.config/lab.hcl. The file has to be readable by the user running Weblate.

Note

Use the username you configured lab with, as GITLAB_USERNAME (WEBLATE_GITLAB_USERNAME for the Docker image).

Gerrit¶

New in version 2.2.

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

The Gerrit documentation has the details on the configuration necessary to set up such repositories.

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 breaks Weblate integration.

See also

See Accessing repositories for info on how to access different kinds of repositories.

Subversion¶

New in version 2.8.

Weblate uses git-svn to interact with subversion repositories. It is a Perl script that lets subversion be used by a Git client, enabling users to maintain 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/). More info about this is to be foud in the git-svn documentation. If your repository does not have a standard layout and you encounter erros, try including the branch name in the repository URL and leaving branch empty.

Changed in version 2.19: Before this, there was only support for standard layout repositories.

Subversion credentials¶

Weblate expects you to have accepted the certificate up-front and if needed, your credentials. It will look to insert them into the DATA_DIR directory. Accept the certificate by using svn once with the $HOME environment variable set to the DATA_DIR:

# Use DATA_DIR as configured in Weblate settings.py, it is /app/data in the Docker
HOME=${DATA_DIR}/home svn co https://svn.example.com/example

See also

DATA_DIR

Local files¶

New in version 3.8.

Weblate can also operate without a remote VCS. The initial translations are imported by uploading them. Later you can replace individual files by file upload, or add translation strings directly from Weblate (currently available only for monolingual translations).

In the background Weblate creates a Git repository for you and all changes are tracked in in. In case you later decide to use a VCS to store the translations, you already have a repo within Weblate can base your integration on.

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 5000 requests per hour 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/"
}

Users¶

New in version 4.0.

GET /api/users/¶: Returns a list of users if you have permissions to see manage users. If not, then you get to see only your own details.

See also

Users object attributes are documented at GET /api/users/(str:username)/.

GET /api/users/(str: username)/¶

Returns information about users.

Parameters:

username (string) – User’s username

Response JSON Object:

username (string) – username of a user
full_name (string) – full name of a user
email (string) – email of a user
is_superuser (boolean) – whether the user is a super user
is_active (boolean) – whether the user is active
date_joined (string) – date the user is created
groups (array) – link to associated groups; see GET /api/groups/(int:id)/

PUT /api/users/(str: username)/¶

Changes the user parameters.

Response JSON Object:
Parameters:	username (string) – User’s username
	username (string) – username of a user full_name (string) – full name of a user email (string) – email of a user is_superuser (boolean) – whether the user is a super user is_active (boolean) – whether the user is active date_joined (string) – date the user is created

PATCH /api/users/(str: username)/¶

Changes the user parameters.

Response JSON Object:
Parameters:	username (string) – User’s username
	username (string) – username of a user full_name (string) – full name of a user email (string) – email of a user is_superuser (boolean) – whether the user is a super user is_active (boolean) – whether the user is active date_joined (string) – date the user is created

DELETE /api/users/(str: username)/¶

Deletes all user information and mark the user inactive.

Parameters:	username (string) – User’s username

POST /api/users/(str: username)/groups/¶

Associate groups with a user.

Form Parameters:
Parameters:	username (string) – User’s username
	string group_id – The unique group ID

Groups¶

New in version 4.0.

GET /api/groups/¶: Returns a list of groups if you have permissions to see manage groups. If not, then you get to see only the groups the user is a part of.

See also

Group object attributes are documented at GET /api/groups/(int:id)/.

GET /api/groups/(int: id)/¶

Returns information about group.

Parameters:

id (int) – Group’s ID

Response JSON Object:

name (string) – name of a group
project_selection (int) – integer corresponding to group of projects
language_selection (int) – integer corresponding to group of languages
roles (array) – link to associated roles; see GET /api/roles/(int:id)/
projects (array) – link to associated projects; see GET /api/projects/(string:project)/
components (array) – link to associated components; see GET /api/components/(string:project)/(string:component)/
componentlist (array) – link to associated componentlist; see GET /api/component-lists/(str:slug)/

PUT /api/groups/(int: id)/¶

Changes the group parameters.

Response JSON Object:
Parameters:	id (int) – Group’s ID
	name (string) – name of a group project_selection (int) – integer corresponding to group of projects language_selection (int) – integer corresponding to group of Languages

PATCH /api/groups/(int: id)/¶

Changes the group parameters.

Response JSON Object:
Parameters:	id (int) – Group’s ID
	name (string) – name of a group project_selection (int) – integer corresponding to group of projects language_selection (int) – integer corresponding to group of languages

DELETE /api/groups/(int: id)/¶

Deletes the group.

Parameters:	id (int) – Group’s ID

POST /api/groups/(int: id)/roles/¶

Associate roles with a group.

Form Parameters:
Parameters:	id (int) – Group’s ID
	string role_id – The unique role ID

POST /api/groups/(int: id)/components/¶

Associate components with a group.

Form Parameters:
Parameters:	id (int) – Group’s ID
	string component_id – The unique component ID

DELETE /api/groups/(int: id)/components/(int: component_id)¶

Delete component from a group.

Parameters:	id (int) – Group’s ID component_id (int) – The unique component ID

POST /api/groups/(int: id)/projects/¶

Associate projects with a group.

Form Parameters:
Parameters:	id (int) – Group’s ID
	string project_id – The unique project ID

DELETE /api/groups/(int: id)/projects/(int: project_id)¶

Delete project from a group.

Parameters:	id (int) – Group’s ID project_id (int) – The unique project ID

POST /api/groups/(int: id)/languages/¶

Associate languages with a group.

Form Parameters:
Parameters:	id (int) – Group’s ID
	string language_code – The unique language code

DELETE /api/groups/(int: id)/languages/(string: language_code)¶

Delete language from a group.

Parameters:	id (int) – Group’s ID language_code (string) – The unique language code

POST /api/groups/(int: id)/componentlist/¶

Associate componentlist with a group.

Form Parameters:
Parameters:	id (int) – Group’s ID
	string component_list_id – The unique componentlist ID

DELETE /api/groups/(int: id)/componentlist/(int: component_list_id)¶

Delete componentlist from a group.

Parameters:	id (int) – Group’s ID component_list_id (int) – The unique componentlist ID

Roles¶

GET /api/roles/¶: Returns a list of all roles associated with user. If user is superuser, then list of all existing roles is returned.

See also

Roles object attributes are documented at GET /api/roles/(int:id)/.

GET /api/roles/(int: id)/¶

Returns information about a role.

Response JSON Object:
Parameters:	id (int) – Role ID
	name (string) – Role name permissions (array) – list of codenames of permissions

Example JSON data:

{
    "name": "Access repository",
    "permissions": [
        "vcs.access",
        "vcs.view"
    ],
    "url": "http://example.com/api/roles/1/",
}

PUT /api/roles/(int: id)/¶

Changes the role parameters.

Response JSON Object:
Parameters:	id (int) – Role’s ID
	name (string) – Role name permissions (array) – list of codenames of permissions

PATCH /api/roles/(int: id)/¶

Changes the role parameters.

Response JSON Object:
Parameters:	id (int) – Role’s ID
	name (string) – Role name permissions (array) – list of codenames of permissions

DELETE /api/roles/(int: id)/¶

Deletes the role.

Parameters:	id (int) – Role’s ID

Languages¶

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

See also

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

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

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

POST /api/projects/¶

New in version 3.9.

Creates a new project.

Parameters:	name (string) – Project name slug (string) – Project slug web (string) – Project website source_language (string) – Project source language code (optional)

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/

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/"
}

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

New in version 3.9.

Deletes a project.

Parameters:	project (string) – Project URL slug

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:id)/`

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

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

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)/`

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

New in version 3.9.

Creates translation components in the given project.

Parameters:	project (string) – Project URL slug

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

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/
push (string) – URL of a push repository

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/"
}

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

New in version 3.9.

Deletes a component.

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

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:id)/`

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

Returns a list of component screenshots.

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

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

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.

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

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

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

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

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)/`

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

Creates new translation in the given component.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	language_code (string) – translation language code; see `GET /api/languages/(string:language)/`

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

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/

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/"
}

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

New in version 3.9.

Deletes a translation.

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

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:id)/`

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:id)/`

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

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`, `source`) string fuzzy – Fuzzy strings processing (empty, `process`, `approve`)

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

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

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

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

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

Returns information about translation unit.

Parameters:

id (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
note (string) – translation unit note
flags (string) – translation unit flags
fuzzy (boolean) – whether unit is fuzzy or marked for review
translated (boolean) – whether unit is translated
approved (boolean) – whether translation is approved
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/units/(int:id)/

Changes¶

New in version 2.10.

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

See also

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

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

Returns information about translation change.

Parameters:

id (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

Screenshots¶

New in version 2.14.

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

See also

Screenshot object attributes are documented at GET /api/screenshots/(int:id)/.

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

Returns information about screenshot information.

Response JSON Object:
Parameters:	id (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:id)/file/` units (array) – link to associated source string information; see `GET /api/units/(int:id)/`

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

Download the screenshot image.

Parameters:	id (int) – Screenshot ID

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

Replace screenshot image.

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

CURL example:

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

POST /api/screenshots/(int: id)/units/¶

Associate source string with screenshot.

Form Parameters:
Parameters:	id (int) – Screenshot ID
	string unit_id – Unit ID
Response JSON Object:
	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:id)/file/` units (array) – link to associated source string information; see `GET /api/units/(int:id)/`

POST /api/screenshots/¶

Creates a new screenshot.

Form Parameters:
	file image – Uploaded file string name – Screenshot name string project_slug – Project Slug string component_slug – Component Slug
Response JSON Object:
	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:id)/file/` units (array) – link to associated source string information; see `GET /api/units/(int:id)/`

Component lists¶

New in version 4.0.

GET /api/component-lists/¶: Returns a list of component lists.

See also

Component list object attributes are documented at GET /api/component-lists/(str:slug)/.

GET /api/component-lists/(str: slug)/¶

Returns information about component list.

Response JSON Object:
Parameters:	slug (string) – Component list slug
	name (string) – name of a component list slug (string) – slug of a component list show_dashboard (boolean) – whether to show it on a dashboard components (array) – link to associated components; see `GET /api/components/(string:project)/(string:component)/` auto_assign (array) – automatic assignment rules

PUT /api/component-lists/(str: slug)/¶

Changes the component list parameters.

Request JSON Object:
Parameters:	slug (string) – Component list slug
	name (string) – name of a component list slug (string) – slug of a component list show_dashboard (boolean) – whether to show it on a dashboard

PATCH /api/component-lists/(str: slug)/¶

Changes the component list parameters.

Request JSON Object:
Parameters:	slug (string) – Component list slug
	name (string) – name of a component list slug (string) – slug of a component list show_dashboard (boolean) – whether to show it on a dashboard

DELETE /api/component-lists/(str: slug)/¶

Deletes the component list.

Parameters:	slug (string) – Component list slug

PUT /api/component-lists/(str: slug)/components/¶

Associate component with a component list.

Form Parameters:
Parameters:	slug (string) – Component list slug
	string component_id – Component ID

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/en/github/extending-github/about-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/¶

New in version 3.3.

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/¶

New in version 3.8.

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/en-us/azure/devops/service-hooks/services/webhooks: Generic information about Azure Repos Web Hooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/gitea/¶

New in version 3.9.

Special hook for handling Gitea Webhook notifications and automatically updating matching components.

See also

Automatically receiving changes from Gitea Repos: For instruction on setting up Gitea integration
https://docs.gitea.io/en-us/webhooks/: Generic information about Gitea Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/gitee/¶

New in version 3.9.

Special hook for handling Gitee Webhook notifications and automatically updating matching components.

See also

Automatically receiving changes from Gitee Repos: For instruction on setting up Gitee integration
https://gitee.com/help/categories/40: Generic information about Gitee Webhooks
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: There has been full wlc utility support ever 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

Getting started¶

Configuration is stored in ~/.config/weblate:

[weblate]
url = https://hosted.weblate.org/api/

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

You can then invoke commands on the default server:

wlc ls
wlc commit sandbox/hello-world

See also

Configuration files

Synopsis¶

wlc [parameter] <command> [options]

Commands actually indicate which operation should be performed.

Description¶

Weblate Client is a 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.

Instance wide options¶

The program accepts the following options for a whole instance, which must be entered before any subcommand.

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

--url URL¶: Specify the API URL. Overrides any value found in the configuration file, see Configuration files. The URL should end with /api/, for example https://hosted.weblate.org/api/.

--key KEY¶: Specify the API user key to use. Overrides any value found in the configuration file, see Configuration files. You can find your key in your profile on Weblate.

--config PATH¶: Overrides the configuration file path, see Configuration files.

--config-section SECTION¶: Overrides configuration file section in use, see Configuration files.

Subcommands¶

The following subcommands are available:

version¶: Prints the current version.

list-languages¶: Lists used languages in Weblate.

list-projects¶: Lists projects in Weblate.

list-components¶: Lists components in Weblate.

list-translations¶: Lists translations in Weblate.

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

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

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

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

push¶: Pushes Weblate object changes 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 a Weblate object to match the remote repository (translation, component or project).

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

statistics¶: Displays detailed statistics for a 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 further translation in Weblate.

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

Unlocks translation of Weblate component.

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

Displays changes for a given object.

download¶

New in version 0.7: Supported since wlc 0.7.

Downloads a translation file.

--convert¶: Converts file format, if unspecified no conversion happens on the server and the file is downloaded as is to the repository.

--output¶: Specifies file to save output in, if left unspecified it is printed to stdout.

upload¶

New in version 0.9: Supported since wlc 0.9.

Uploads a translation file.

--overwrite¶: Overwrite existing translations upon uploading.

--input¶: File from which content is read, if left unspecified it is read from stdin.

Configuration files¶

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

The program follows the 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 to the default translation - component or project.

The configuration file is an 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 using the .weblate configuration in the VCS repository so that wlc knows which server it should talk to.

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 designate what project wlc should work on:

$ 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 this setup it is easy to commit pending changes in the current project:

$ wlc commit

Weblate’s Python API¶

Installation¶

The Python API is shipped separately, you need to install the 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 a single API GET call.

post(path, **kwargs)¶

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

Performs a 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 the wlc configuration file (~/.config/wlc) placed in your XDG configuration path (/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.

Configuration instructions¶

Installing Weblate¶

Installing using Docker¶

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

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¶

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 a root user. This has lead to changed exposed port from 80 to 8080.

See also

Invoking management commands

Docker container with HTTPS support¶

Please see Installation for generic deployment instructions, this section only mentions differences compared to it.

Using own SSL certificates¶

New in version 3.8-3.

In case you have own SSL certificate you want to use, simply place the files into the Weblate data volume (see Docker container volumes):

ssl/fullchain.pem containing the certificate including any needed CA certificates
ssl/privkey.pem containing the private key

Additionally, Weblate container will now accept SSL connections on port 4443, you will want to include the port forwarding for HTTPS in docker compose override:

version: '3'
services:
  weblate:
    ports:
      - 80:8080
      - 443:4443

Automatic SSL certificates using Let’s Encrypt¶

In case you want to use Let’s Encrypt automatically generated SSL certificates on public installation, you need to add a reverse HTTPS proxy an additional Docker container, https-portal will be used for that. 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.

You might also want to update the docker-compose repository, though it’s not needed in most case. Please beware of PostgreSQL version changes in this case as it’s not straightforward to upgrade the database, see GitHub issue for more info.

Admin login¶

After container setup, you can sign in as admin user with password provided in WEBLATE_ADMIN_PASSWORD, or a random password generated on first start if that was not set.

To reset admin password, restart the container with WEBLATE_ADMIN_PASSWORD set to new password.

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. It is used for both ADMINS setting and creating admin user (see WEBLATE_ADMIN_PASSWORD for more info on that).

Example:

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

WEBLATE_ADMIN_PASSWORD¶

Sets the password for the admin user.

If not set and admin user does not exist, it is created with a random password shown on first container startup.
If not set and admin user exists, no action is performed.
If set the admin user is adjusted on every container startup to match WEBLATE_ADMIN_PASSWORD, WEBLATE_ADMIN_NAME and WEBLATE_ADMIN_EMAIL.

Warning

It might be a security risk to store password in the configuration file. Consider using this variable only for initial setup (or let Weblate generate random password on initial startup) or for password recovery.

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 configure that as well, see Docker container with HTTPS support for examples.

Example:

environment:
  WEBLATE_ENABLE_HTTPS: 1

See also

Set correct site domain

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¶

WEBLATE_ADD_LOGIN_REQUIRED_URLS_EXCEPTIONS¶

WEBLATE_REMOVE_LOGIN_REQUIRED_URLS_EXCEPTIONS¶

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

You can either replace whole settings, or modify default value using ADD and REMOVE variables.

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 requests, Setting up hub

WEBLATE_GITLAB_USERNAME¶: Configures GitLab username for GitLab merge-requests by changing GITLAB_USERNAME

See also

Pushing changes to GitLab as merge requests Setting up Lab

WEBLATE_GITLAB_HOST¶: Configures GitLab Host for GitLab merge-requests

See also

Pushing changes to GitLab as merge requests Setting up Lab

WEBLATE_GITLAB_TOKEN¶: Configures GitLab access token for GitLab merge-requests

See also

Pushing changes to GitLab as merge requests Setting up Lab

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

WEBLATE_URL_PREFIX¶: Configures URL prefix where Weblate is running, see URL_PREFIX.

WEBLATE_SILENCED_SYSTEM_CHECKS¶: Configures checks which you do not want to be displayed, see SILENCED_SYSTEM_CHECKS.

Machine translation settings¶

WEBLATE_MT_AWS_REGION¶

WEBLATE_MT_AWS_ACCESS_KEY_ID¶

WEBLATE_MT_AWS_SECRET_ACCESS_KEY¶

Configures AWS machine translation.

environment:
  WEBLATE_MT_AWS_REGION: us-east-1
  WEBLATE_MT_AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
  WEBLATE_MT_AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

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.

Example:

environment:
  WEBLATE_MT_MYMEMORY_ENABLED: 1

WEBLATE_MT_GLOSBE_ENABLED¶

Enables Glosbe machine translation.

environment:
  WEBLATE_MT_GLOSBE_ENABLED: 1

WEBLATE_MT_MICROSOFT_TERMINOLOGY_ENABLED¶

Enables Microsoft Terminology Service machine translation.

environment:
  WEBLATE_MT_MICROSOFT_TERMINOLOGY_ENABLED: 1

WEBLATE_MT_SAP_BASE_URL¶

WEBLATE_MT_SAP_SANDBOX_APIKEY¶

WEBLATE_MT_SAP_USERNAME¶

WEBLATE_MT_SAP_PASSWORD¶

WEBLATE_MT_SAP_USE_MT¶

Configures SAP Translation Hub machine translation.

environment:
    WEBLATE_MT_SAP_BASE_URL: "https://example.hana.ondemand.com/translationhub/api/v1/"
    WEBLATE_MT_SAP_USERNAME: "user"
    WEBLATE_MT_SAP_PASSWORD: "password"
    WEBLATE_MT_SAP_USE_MT: 1

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¶

WEBLATE_AUTH_LDAP_USER_SEARCH¶

WEBLATE_AUTH_LDAP_USER_SEARCH_FILTER¶

LDAP authentication configuration.

Example for direct bind:

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

Example for search and bind:

environment:
  WEBLATE_AUTH_LDAP_SERVER_URI: ldap://ldap.example.org
  WEBLATE_AUTH_LDAP_BIND_DN: CN=ldap,CN=Users,DC=example,DC=com
  WEBLATE_AUTH_LDAP_BIND_PASSWORD: password
  WEBLATE_AUTH_LDAP_USER_ATTR_MAP: full_name:name,email:mail
  WEBLATE_AUTH_LDAP_USER_SEARCH: CN=Users,DC=example,DC=com

Example with search and bind against Active Directory:

environment:
  WEBLATE_AUTH_LDAP_BIND_DN: CN=ldap,CN=Users,DC=example,DC=com
  WEBLATE_AUTH_LDAP_BIND_PASSWORD: password
  WEBLATE_AUTH_LDAP_SERVER_URI: ldap://ldap.example.org
  WEBLATE_AUTH_LDAP_USER_ATTR_MAP: full_name:name,email:mail
  WEBLATE_AUTH_LDAP_USER_SEARCH: CN=Users,DC=example,DC=com
  WEBLATE_AUTH_LDAP_USER_SEARCH_FILTER: (sAMAccountName=%(user)s)

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.

Keycloak¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_KEY¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_SECRET¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_ALGORITHM¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL¶

WEBLATE_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL¶: Enables Keycloak authentication, see documentation.

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¶

Slack¶

WEBLATE_SOCIAL_AUTH_SLACK_KEY¶

SOCIAL_AUTH_SLACK_SECRET¶: Enables Slack authentication, see Slack.

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

Database setup for Weblate

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

Database backup settings¶

See also

Dumped data for backups

WEBLATE_DATABASE_BACKUP¶: Configures the daily database dump using DATABASE_BACKUP. Defaults to plain.

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.

REDIS_TLS¶: Enables using SSL for Redis connection.

REDIS_VERIFY_SSL¶: Can be used to disable SSL certificate verification for Redis connection.

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

WEBLATE_EMAIL_BACKEND¶: Configures Django backend to use for sending e-mails.

See also

Configure e-mail addresses, EMAIL_BACKEND

Error reporting¶

It is recommended to collect errors from the installation systematically, 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_ENVIRONMENT¶: Your Sentry Environment (optional).

Changing enabled apps, checks, addons or autofixes¶

New in version 3.8-5.

The built in configuration of enabled checks, addons or autofixes can be adjusted by following variables:

WEBLATE_ADD_APPS¶

WEBLATE_REMOVE_APPS¶

WEBLATE_ADD_CHECK¶

WEBLATE_REMOVE_CHECK¶

WEBLATE_ADD_AUTOFIX¶

WEBLATE_REMOVE_AUTOFIX¶

WEBLATE_ADD_ADDONS¶

WEBLATE_REMOVE_ADDONS¶

For example:

Example:

environment:
  WEBLATE_REMOVE_AUTOFIX: weblate.trans.autofixes.whitespace.SameBookendingWhitespace
  WEBLATE_ADD_ADDONS: customize.addons.MyAddon,customize.addons.OtherAddon

Docker container volumes¶

There is single data volume exported by the Weblate container. The other service containers (PostgreSQL or Redis) have their data volumes as well, but those are not covered by this document.

The data volume is used to store Weblate persistent data such as cloned repositories or to customize Weblate installation.

The placement of the Docker volume on host system depends on your Docker configuration, but usually it is stored in /var/lib/docker/volumes/weblate-docker_weblate-data/_data/. In the container it is mounted as /app/data.

See also

Docker volumes documentation

Further configuration customization¶

You can further customize Weblate installation in the data volume, see Docker container volumes.

Custom configuration files¶

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

Replacing logo and other static files¶

New in version 3.8-5.

The static files coming with Weblate can be overridden by placing into /app/data/python/customize/static (see Docker container volumes). For example creating /app/data/python/customize/static/favicon.ico will replace the favicon.

Hint

The files are copied to correspoding location on container startup, so restart is needed after changing the volume content.

Alternatively you can also include own module (see Customizing Weblate) and add it as separate volume to the Docker container, for example:

weblate:
  volumes:
    - weblate-data:/app/data
    - ./weblate_customization/weblate_customization:/app/data/python/weblate_customization
  environment:
    WEBLATE_ADD_APPS: weblate_customization

Adding own Python modules¶

New in version 3.8-5.

You can place own Python modules in /app/data/python/ (see Docker container volumes) and they can be then loaded by Weblate, most likely by using Custom configuration files.

See also

Customizing Weblate

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.

Lab setup¶

In order to use GitLab’s merge-request feature, you must initialize lab configuration by entering the weblate contained and executing lab command. For example:

docker-compose exec --user weblate weblate bash
cd
HOME=/app/data/home lab

You can also use environment variables to configure lab on each container start. Just add WEBLATE_GITLAB_USERNAME, WEBLATE_GITLAB_HOST``and ``WEBLATE_GITLAB_TOKEN to your env configuration.

weblate:
  environment:
    WEBLATE_GITLAB_USERNAME: translations_bot
    WEBLATE_GITLAB_HOST: https://gitlab.example.com
    WEBLATE_GITLAB_TOKEN: personal_access_token_of_translations_bot

The access_token passed for lab configuratoin must be same as GITLAB_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.

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 libacl1-dev libssl-dev \
   build-essential python3-gdbm python3-dev python3-pip python3-virtualenv virtualenv git

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¶

Note

Following steps assume virtualenv used by Weblate is active (what can be done by . ~/weblate-env/bin/activate). In case this is not true, you will have to specify full path to weblate command as ~/weblate-env/bin/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 PostgreSQL, check Database setup for Weblate for production 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 libacl-devel \
   python3-pip python3-virtualenv python3-devel git

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¶

Note

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 PostgreSQL, check Database setup for Weblate for production 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 pango-devel gobject-introspection-devel libacl-devel \
   python3-pip python3-virtualenv python3-devel git

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

dnf install tesseract-langpack-eng 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

# 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¶

Note

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 PostgreSQL, check Database setup for Weblate for production 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 macOS¶

Warning

This guide is currently untested, please provide feedback or corrections to it.

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):

brew install pango cairo libjpeg python git libyaml gobject-introspection
pip3 install virtualenv

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

brew install tesseract

The local installation instructions:

# Web server option 1: NGINX and uWSGI
brew install nginx uwsgi

# Web server option 2: Apache with ``mod_wsgi``
brew install httpd

# Caching backend: Redis
brew install redis

# Database server: PostgreSQL
brew install postgresql

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¶

Note

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 PostgreSQL, check Database setup for Weblate for production 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):
```
weblate migrate
weblate collectstatic
weblate compilemessages
```
Note

This step should be repeated whenever you update the repository.

Installing on OpenShift¶

Note

This guide is looking for contributors expereinced with OpenShift, see <https://github.com/WeblateOrg/weblate/issues/2889>.

Weblate supports OpenShift, the needed integration files are in main repository in the openshift3 directory.

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.

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 3.6 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/
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://pango.gnome.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. All files within this directory should be owned and writable by user running Weblate.

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 a PostgreSQL database server.

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 --superuser --pwprompt weblate

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

Hint

If you don’t want to make Weblate user a superuser in PostgreSQL, you can omit that. In that case you will have to perform some of the migration steps manually as a PostgreSQL superuser:

CREATE EXTENSION IF NOT EXISTS pg_trgm;

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 and MariaDB¶

Weblate can be also used with MySQL or MariaDB, please see MySQL notes and MariaDB notes for caveats using Django with those.

Following configuration is recommended for Weblate:

Use utf8mb4 charset to allow representation of higher Unicode planes (for example emojis).
Configure the server with Innodb_large_prefix to allow longer indices on text fields.
Set isolcation level to READ COMMITTED.
The SQL mode should be set to STRICT_TRANS_TABLES.

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

You need to set this to list the hosts your site is supposed to serve. For example:
ALLOWED_HOSTS = ['demo.weblate.org']
Alternatively you can include wildcard:
ALLOWED_HOSTS = ['*']
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: weblate 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 weblate 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 weblate migrate --noinput, and then create an admin user using createadmin command.

You should also sign 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 an exclamation mark in the top bar if signed in as a superuser:

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

weblate 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 site domain¶

Adjust site name and domain 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 and enforcing 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:

weblate changesite --set-name 127.0.0.1:8000

For a production site, you want something like:

weblate 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:

ENABLE_HTTPS = True

Hint

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

See also

ENABLE_HTTPS, Set correct site domain

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'

Note

To disable sending e-mails by Weblate set EMAIL_BACKEND to django.core.mail.backends.dummy.EmailBackend.

This will disable all e-mail delivery including registration or pasword reset e-mails.

Allowed hosts setup¶

Django requires 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.

System locales and encoding¶

The system locales should be configured to UTF-8 capable ones. On most Linux distributions this is the default setting. In case it is not the case on your system, please change locales to UTF-8 variant.

For examble by editing /etc/default/locale and setting there LANG="C.UTF-8".

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:

weblate runserver

Warning

DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through security audits or performance tests. See also Django documentation on runserver.

Hint

The Django built in server serves static files only with DEBUG enabled as it is intended for development only. For production use, please see wsgi setups in Sample configuration for NGINX and uWSGI, Sample configuration for Apache, Sample configuration for Apache and Gunicorn, and Serving static files.

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 weblate 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

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/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/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 /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 /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       = python3
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /home/weblate/weblate-env/lib/python3.7/site-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 = /home/weblate/weblate-env

# Needed for OAuth/OpenID
buffer-size   = 8192

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

# Enable threads for Sentry error submission
enable-threads = true

# 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/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

Running Celery as system service¶

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
RuntimeDirectory=celery
RuntimeDirectoryPreserve=restart
LogsDirectory=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 backup translate"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/home/weblate/weblate-env/bin/celery"

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

# 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=10 \
    --concurrency:memory=1 --queues:memory=memory --prefetch-multiplier:memory=4 \
    --concurrency:translate=4 --queues:translate=translate --prefetch-multiplier:translate=4 \
    --concurrency:backup=1 --queues:backup=backup  --prefetch-multiplier:backup=2"

# 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
}

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.

Periodic tasks using Celery beat¶

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

The tasks are supposed to be executed by Celery beats deamon. In case it it not working properly, it might be not running or it’s database was corrupted. Check the Celery startup logs in such case to figure out root cause.

Monitoring Celery status¶

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.

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 set SENTRY_DSN in the settings.py:

SENTRY_DSN = "https://id@your.sentry.example.com/"

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
weblate dumpdata > /tmp/weblate.dump
# Import dump
weblate 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.

Other notes¶

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

Weblate deployments¶

Weblate can be easily installed in your cloud. Please find detailed guide for your platform:

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¶

Docker image upgrades¶

The official Docker image (see Installing using Docker) has all upgrade steps integrated. There are no manual step besides pulling latest version.

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.

Stop wsgi and Celery processes. The upgrade can perform incompatible changes in the database, so it is always safer to avoid old processes running while upgrading.
Upgrade Weblate code. For pip installs it can be achieved by pip install -U Weblate for Git checkout git pull should do it.
Upgrade configuration file, refer to settings_example.py or Version specific instructions for needed steps.
Upgrade database structure:
```
weblate migrate --noinput
```
Collect updated static files (mostly javascript and CSS):
```
weblate collectstatic --noinput
```
If you are running version from Git, you should also regenerate locale files every time you are upgrading. You can do this by invoking:
```
weblate compilemessages
```
Verify that your setup is sane (see also Production setup):
```
weblate 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.