Welcome to Weblate’s documentation!¶

Upgrade from 2.3 to 2.4¶

Handling of static content has been rewritten, please adjust configuration of your webserver accordingly (see Serving static files for more details). Most importantly:

/media/ path is no longer used
/static/ path now holds both admin and Weblate static files

There is now also additional dependency - django_compressor, please install it prior to upgrading.

See also

Upgrade from 2.4 to 2.5¶

The fulltext index has been changed, so unless you rebuild it, the fulltext search will not work. To rebuild it, execute:

./manage.py rebuild_index --clean --all

See also

Upgrade from 2.5 to 2.6¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

new dependecy on Django REST Framework, see Software requirements
example configuration now configures Django REST Framework, please adjust your settings accordingly
the USE_TZ settings is now enabled by default

Note

Weblate now much more relies on correct site name in the database, please see Set correct site name for instructions how to set it up.

See also

Upgrade from 2.6 to 2.7¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

new optional dependency on python-bidi, see Software requirements
Google Web Translation was removed, remove it from your configuration

See also

Upgrade from 2.7 to 2.8¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

new dependency on defusedxml, see Software requirements
there is new quality check: Invalid XML markup

See also

Upgrade from 2.8 to 2.9¶

Please follow generic upgrade instructions, the only notable change is addition of media storage to DATA_DIR.

See also

Upgrade from 2.9 to 2.10¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

The INSTALLED_APPS now should include weblate.utils.
There is new check in default set (SamePluralsCheck).
There is change in SOCIAL_AUTH_PIPELINE default settings.
You might want to enable optional Git exporter.
There is new RemoveControlChars in default AUTOFIX_LIST.
If you are using Microsoft Translator, please replace Microsoft Translator with Microsoft Cognitive Services Translator, Microsoft has changed authentication scheme.

See also

Upgrade from 2.10 to 2.11¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

There is new recommended value for SOCIAL_AUTH_SLUGIFY_FUNCTION.
There is change in MIDDLEWARE_CLASSES setting.
The python-social-auth module has been deprecated upstream, Weblate now uses social-auth-core and social-auth-app-django instead. You also have to adjust settings.py as several modules have been moved from social to either social_core or social_django. Please consult settings_example.py for correct values.

Warning

If you were using python-social-auth 0.2.19 or older with Weblate 2.10, you should first upgrade Weblate 2.10 to python-social-auth 0.2.21 and then perform upgrade to Weblate 2.11. Otherwise you end up with non applicable database migrations.

See Migrating from python-social-auth to split social for more information.

See also

Upgrade from 2.11 to 2.12¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

The database migration will take quite long on this update as all translation units stored in database have to be updated. Expect about 1 hour of migration for 500000 translation units (depends on hardware and database).
There is new dependency on django-appconf and siphashc3.
The setting for UNAUTHENTICATED_USER for REST_FRAMEWORK has been changed to properly handle anonymous user permissions in REST API.
The INSTALLED_APPS now should include weblate.screenshots.
There is new optional dependency on tesserocr, see Software requirements.

See also

Upgrade from 2.12 to 2.13¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

There is new quality check: Has been translated.
The INSTALLED_APPS now should include weblate.permissions.
The per project ALCs are now implemented using Group ACL, you might need to adjust your setup if you were using Group ACLs before, see Group-based access control for more information about the setup.
There are several new permissions which should be assigned to default groups, you should run ./manage.py setupgroups to update them. Alternatively you might want to add following permissions where applicable (see Extra privileges for their default setup):
- Can access VCS repository
- Can access project

Note

See also

Upgrade from 2.13 to 2.14¶

Follow generic upgrade instructions, there is no special change.

Notable configuration or dependencies changes:

There is new middleware weblate.middleware.SecurityMiddleware in the default configuration, see Content security policy for more details.
Weblate now uses Django password validation, it’s controlled by AUTH_PASSWORD_VALIDATORS setting.
Weblate now customizes disconnect pipeline for Python Social Auth, the SOCIAL_AUTH_DISCONNECT_PIPELINE setting is now needed.
There is change in SOCIAL_AUTH_PIPELINE default settings.
All pending email verifications will be invalid due to validation change.
The authentication attempts are now rate limited, see Rate limiting for more details.

See also

Python Social Auth backend

Upgrading to Django 1.7¶

Changed in version 2.3: This migration is supported only in Weblate 2.2, in case you are upgrading from some older version, you will have to do intermediate update to 2.2.

Django 1.7 has a new feature to handle database schema upgrade called “migrations” which is incompatible with South (used before by Weblate).

Before migrating to Django 1.7, you first need to apply all migrations from South. If you already have upgraded Django to 1.7, you can do this using virtualenv and examples/migrate-south script:

examples/migrate-south --settings weblate.settings

Once you have done that, you can run Django migrations and work as usual. For the initial setup, you might need to fake some of the migrations though:

./manage.py migrate --fake-initial

Migrating from Pootle¶

As Weblate was originally written as replacement from Pootle, it is supported to migrate user accounts from Pootle. All you need to do is to copy auth_user table from Pootle, user profiles will be automatically created for users as they log in and they will be asked to update their settings. Alternatively you can use importusers to import dumped user credentials.

Authentication¶

User registration¶

The default setup for Weblate is to use python-social-auth for handling new users. This allows them to register using form on the website and after confirming their email they can contribute or by using some third party service to authenticate.

You can also completely disable new users registration using REGISTRATION_OPEN.

Rate limiting¶

New in version 2.14.

The password based authentication is subject to rate limiting. At most AUTH_MAX_ATTEMPTS attempts are allowed within AUTH_CHECK_WINDOW seconds. The user is then blocked for AUTH_LOCKOUT_TIME.

If there are more than AUTH_LOCK_ATTEMPTS failed authentication attempts on one account, this account password authentication is disabled and it’s not possible to login until user asks for password reset.

IP address for rate limiting¶

The rate limiting is based on client IP address. This is obtained from HTTP headers and you will have to change configuration in case Weblate is running behind reverse proxy to work it properly.

Authentication backends¶

By default Weblate uses Django built-in authentication and includes various social authentication options. Thanks to using Django authentication, you can also import user database from other Django based projects (see Migrating from Pootle).

Django can be additionally configured to authenticate against other means as well.

Social authentication¶

Thanks to python-social-auth, Weblate support authentication using many third party services such as Facebook, GitHub, Google or Bitbucket.

Please check their documentation for generic configuration instructions in Django Framework.

Note

By default, Weblate relies on third-party authentication services to provide validated email address, in case some of services you want to use do not support this, please remove social_core.pipeline.social_auth.associate_by_email from SOCIAL_AUTH_PIPELINE settings.

Enabling individual backends is quite easy, it’s just a matter of adding entry to AUTHENTICATION_BACKENDS setting and possibly adding keys needed for given authentication. Please note that some backends do not provide user email by default, you have to request it explicitly, otherwise Weblate will not be able to properly credit users contributions.

OpenID authentication¶

For OpenID based services it’s usually just a matter of enabling them. Following section enables OpenID authentication for OpenSUSE, Fedora and Ubuntu:

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.email.EmailAuth',
    'social_core.backends.suse.OpenSUSEOpenId',
    'social_core.backends.ubuntu.UbuntuOpenId',
    'social_core.backends.fedora.FedoraOpenId',
    'weblate.accounts.auth.WeblateUserBackend',
)

GitHub authentication¶

You need to register application on GitHub and then tell Weblate all the secrets:

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.github.GithubOAuth2',
    'social_core.backends.email.EmailAuth',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_GITHUB_KEY = 'GitHub Client ID'
SOCIAL_AUTH_GITHUB_SECRET = 'GitHub Client Secret'
SOCIAL_AUTH_GITHUB_SCOPE = ['user:email']

See also

Bitbucket authentication¶

You need to register application on Bitbucket and then tell Weblate all the secrets:

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.bitbucket.BitbucketOAuth',
    'social_core.backends.email.EmailAuth',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_BITBUCKET_KEY = 'Bitbucket Client ID'
SOCIAL_AUTH_BITBUCKET_SECRET = 'Bitbucket Client Secret'
SOCIAL_AUTH_BITBUCKET_VERIFIED_EMAILS_ONLY = True

See also

Python Social Auth backend

Google OAuth2¶

For using Google OAuth2, you need to register application on <https://console.developers.google.com/> and enable Google+ API.

The redirect URL is https://WEBLATE SERVER/accounts/complete/google-oauth2/

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.google.GoogleOAuth2',
    'social_core.backends.email.EmailAuth',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = 'Client ID'
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = 'Client secret'

Facebook OAuth2¶

As usual with OAuth2 services, you need to register your application with Facebook. Once this is done, you can configure Weblate to use it:

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.facebook.FacebookOAuth2',
    'social_core.backends.email.EmailAuth',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_FACEBOOK_KEY = 'key'
SOCIAL_AUTH_FACEBOOK_SECRET = 'secret'
SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', 'public_profile']

Gitlab OAuth2¶

For using Gitlab OAuth2, you need to register application on <https://gitlab.com/profile/applications>.

The redirect URL is https://WEBLATE SERVER/accounts/complete/gitlab/ and ensure to mark the read_user scope.

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social_core.backends.gitlab.GitLabOAuth2',
    'social_core.backends.email.EmailAuth',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_GITLAB_KEY = 'Application ID'
SOCIAL_AUTH_GITLAB_SECRET = 'Secret'

LDAP authentication¶

LDAP authentication can be best achieved using django-auth-ldap package. You can install it by usual means:

# Using PyPI
pip install django-auth-ldap

# Using apt-get
apt-get install python-django-auth-ldap

Once you have the package installed, you can hook it to Django authentication:

# Add LDAP backed, keep Django one if you want to be able to login
# even without LDAP for admin account
AUTHENTICATION_BACKENDS = (
    'django_auth_ldap.backend.LDAPBackend',
    'weblate.accounts.auth.WeblateUserBackend',
)

# LDAP server address
AUTH_LDAP_SERVER_URI = 'ldaps://ldap.example.net'

# DN to use for authentication
AUTH_LDAP_USER_DN_TEMPLATE = 'cn=%(user)s,o=Example'
# Depending on your LDAP server, you might use different DN
# like:
# AUTH_LDAP_USER_DN_TEMPLATE = 'ou=users,dc=example,dc=com'

# List of attributes to import from LDAP on login
# Weblate stores full user name in the first_name attribute
AUTH_LDAP_USER_ATTR_MAP = {
    'first_name': 'name',
    'email': 'mail',
}

See also

Django Authentication Using LDAP

CAS authentication¶

CAS authentication can be achieved using a package such as django-cas-ng.

Step one is disclosing the email field of the user via CAS. This has to be configured on the CAS server itself and requires you run at least CAS v2 since CAS v1 doesn’t support attributes at all.

Step two is updating Weblate to use your CAS server and attributes.

To install django-cas-ng:

pip install django-cas-ng

Once you have the package installed you can hook it up to the Django authentication system by modifying the settings.py file:

# Add CAS backed, keep Django one if you want to be able to login
# even without LDAP for admin account
AUTHENTICATION_BACKENDS = (
    'django_cas_ng.backends.CASBackend',
    'weblate.accounts.auth.WeblateUserBackend',
)

# CAS server address
CAS_SERVER_URL = 'https://cas.example.net/cas/'

# Add django_cas_ng somewhere in the list of INSTALLED_APPS
INSTALLED_APPS = (
    ...,
    'django_cas_ng'
)

Finally, a signal can be used to map the email field to the user object. For this to work you have to import the signal from the django-cas-ng package and connect your code with this signal. Doing this inside your settings file can cause problems, therefore it’s suggested to put it:

in your app config’s django.apps.AppConfig.ready() method (Django 1.7 and higher)
at the end of your models.py file (Django 1.6 and lower)
in the project’s urls.py file (when no models exist)

from django_cas_ng.signals import cas_user_authenticated
from django.dispatch import receiver
@receiver(cas_user_authenticated)
def update_user_email_address(sender, user=None, attributes=None, **kwargs):
    # If your CAS server does not always include the email attribute
    # you can wrap the next two lines of code in a try/catch block.
    user.email = attributes['email']
    user.save()

See also

Django CAS NG

Access control¶

Weblate uses privileges system based on Django, but is extended in several ways to allow managing access at more fine grained level. See Per project access control and Group-based access control for more detailed information on those extensions.

The default setup (after you run setupgroups) consists of three groups Guests, Users and Managers which have privileges as described above. All new users are automatically added to Users group (thanks to Automatic group assignments). The Guests groups is used for not logged in users.

To customize this setup, it is recommended to remove privileges from Users group and create additional groups with finer privileges (eg. Translators group, which will be allowed to save translations and manage suggestions) and add selected users to this group. You can do all this from Django admin interface.

To completely lock down your Weblate installation you can use LOGIN_REQUIRED_URLS for forcing users to login and REGISTRATION_OPEN for disallowing new registrations.

Warning

Never remove Weblate predefined groups (Guests, Users and Managers). If you do not want to use these features, just remove all privileges from them.

Extra privileges¶

Weblate defines following extra privileges:

Can upload translation [Users, Managers]: Uploading of translation files.
Can overwrite with translation upload [Users, Managers]: Overwriting existing translations by uploading translation file.
Can define author of translation upload [Managers]: Allows to define custom authorship when uploading translation file.
Can force committing of translation [Managers]: Can force VCS commit in the web interface.
Can see VCS repository URL [Users, Managers, Guests]: Can see VCS repository URL inside Weblate
Can update translation from VCS [Managers]: Can force VCS pull in the web interface.
Can push translations to remote VCS [Managers]: Can force VCS push in the web interface.
Can do automatic translation using other project strings [Managers]: Can do automatic translation based on strings from other components
Can lock whole translation project [Managers]: Can lock translation for updates, useful while doing some major changes in the project.
Can reset translations to match remote VCS [Managers]: Can reset VCS repository to match remote VCS.
Can access VCS repository [Users, Managers, Guests]: Can access the underlying VCS repository (see Git exporter).
Can save translation [Users, Managers]: Can save translation (might be disabled with Suggestion voting).
Can save template [Users, Managers]: Can edit source strings (usually English)
Can accept suggestion [Users, Managers]: Can accept suggestion (might be disabled with Suggestion voting).
Can delete suggestion [Users, Managers]: Can delete suggestion (might be disabled with Suggestion voting).
Can delete comment [Managers]: Can delete comment.
Can vote for suggestion [Users, Managers]: Can vote for suggestion (see Suggestion voting).
Can override suggestion state [Managers]: Can save translation, accept or delete suggestion when automatic accepting by voting for suggestions is enabled (see Suggestion voting).
Can import dictionary [Users, Managers]: Can import dictionary from translation file.
Can add dictionary [Users, Managers]: Can add dictionary entries.
Can change dictionary [Users, Managers]: Can change dictionary entries.
Can delete dictionary [Users, Managers]: Can delete dictionary entries.
Can lock translation for translating [Users, Managers]: Can lock translation while translating (see Translation locking).
Can add suggestion [Users, Managers, Guests]: Can add new suggestions.
Can use machine translation [Users, Managers]: Can use machine translations (see Machine translation).
Can manage ACL rules for a project [Managers]: Can add users to ACL controlled projects (see Per project access control)
Can access project [Users, Managers, Guests]: Can access project (see Per project access control)
Can edit priority [Managers]: Can adjust source string priority
Can edit check flags [Managers]: Can adjust source string check flags
Can download changes [Managers]: Can download changes in a CSV format.
Can display reports [Managers]: Can display detailed translation reports.
Can add translation [Users, Managers]: Can start translations in new language.
Can mass add translation [Managers]: Can start translations in several languages at once.
Can delete translation [Managers]: Can remove translation.
Can change sub project [Managers]: Can edit component settings.
Can change project [Managers]: Can edit project settings.
Can upload screenshot [Managers]: Can upload source string screenshot context.

Per project access control¶

New in version 1.4: This feature is available since Weblate 1.4.

Changed in version 2.13: Since Weblate 2.13 the per project access control uses Group-based access control under the hood. You might need some adjustments to your setup if you were using both features.

Note

By enabling ACL, all users are prohibited to access anything within given project unless you add them the permission to do that.

Additionally you can limit users access to individual projects. This feature is enabled by Enable ACL at Project configuration. This automatically creates Group-based access control for this project

To allow access to this project, you have to add the privilege to do so either directly to given user or group of users in Django admin interface. Or using user management on project page as described in Managing per project access control.

See also

Managing users in the admin

Note

Even with ACL enabled some summary information will be available about your project:

Site wide statistics includes counts for all projects
Site wide languages summary includes counts for all projects

Automatic group assignments¶

New in version 2.5.

You can configure Weblate to automatically add users to groups based on their email. This automatic assignment happens only at time of account creation.

This can be configured in the Django admin interface (in the Accounts section).

Group-based access control¶

New in version 2.5: This feature is available since Weblate 2.5.

You can designate groups that have exclusive access to a particular language, project or component, or a combination thereof. This feature is also used to implement Per project access control by automatically created groups for each project. For example, you can use this feature to designate a language-specific translator team with full privileges for their own language.

This works by “locking” given permission for the group(s) in question to the object, the effect of which is twofold.

Firstly, groups that are locked for some object are the only groups that have given privileges on that object. If a user is not a member of the locked group, they cannot edit the object, even if their privileges or group membership allows them to edit other (unlocked) objects.

Secondly, privileges of the locked group don’t apply on objects other than those to which the group is locked. If a user is a member of the locked group which grants them edit privileges, they can only edit the object locked to the group, unless something else grants them a general edit privilege.

This can be configured in the Django admin interface. The recommended workflow is as follows:

Create a new group ACL in the Group ACL section. Pick a project, subproject, language, or a combination, which will be locked to this group ACL.
Define permissions you want to limit by this group ACL.
Use the + (plus sign) button to the right of Groups field to create a new group. In the pop-up window, fill out the group name and assign permissions.
Save the newly created group ACL.
In the Users section of the admin interface, assign users to the newly created group.

For example, you could create a group called czech_translators, assign it full privileges, and lock it to Czech language. From that point on, all users in this groups would get full privileges for the Czech language in all projects and components, but not for any other languages. Also, users who are not members of the czech_translators group would get no privileges on Czech language in any project.

In order to delete a group ACL, make sure that you first delete the group (or remove its privileges), and only then delete the group ACL. Otherwise, there will be a window of time in which the group is “unlocked” and its permissions apply to all objects. In our example, members of czech_translators group would have full privileges for everything that is not locked to other groups.

It is possible to lock multiple groups within a single group ACL. One group can also be locked to multiple objects through multiple group ACLs. As long as a group is recorded in at least one group ACL, it’s considered to be “locked”, and its privileges do not apply outside the locks.

Group ACLs apply in order of specificity. “Component” is considered most specific, “Language” is least specific. Combinations follow the most specific part of the combination: a group ACL that is locked to a particular component is more specific than a group ACL locked to this component’s project and a particular language. That means that members of the component-specific groups will have privileges on the component, and members of the project-and-language-specific groups will not. The latter will, of course, have privileges on their language in all other components of the project.

For project-level actions (such as pushing upstream, setting priority, etc.), you must create a group ACL locked to only the project. Combinations, such as project plus language, only apply to actions on individual translations.

Managing users and groups¶

All users and groups can be managed using Django admin interface, which is available under /admin/ URL.

Managing per project access control¶

Note

This feature only works for ACL controlled projects, see Per project access control.

Users with Can manage ACL rules for a project privilege (see Access control) can also manage users in projects with access control enabled on the project page. You can add or remove users to the project or make them owners.

The user management is available in Tools menu of a project:

See also

Per project access control

Predefined groups¶

Weblate comes with predefined set of groups where you can assign users.

Administration: Has all permissions on the project.

Glossary: Can manage glossary (add or remove entries or upload glossary).

Languages: Can manage translated languages - add or remove translations.

Screenshots: Can manage screenshots - add or remove them and associate them to source strings.

Template: Can edit translation template in Monolingual components.

Translate: Can translate project, including upload of offline translatoins.

VCS: Can manage VCS and access exported repository.

Translation projects¶

Translation organization¶

Weblate organizes translatable content into tree like structure. The toplevel object is Project configuration, which should hold all translations which belong together (for example translation of an application in several versions and/or documentation). On the next level, there is Component configuration, which is actually the component to translate. Here you define VCS repository to use and mask of files to translate. Bellow Component configuration there are individual translations, which are handled automatically by Weblate as the translation files (matching mask defined in Component configuration) appear in VCS repository.

Note

You can share cloned VCS repositories using Weblate internal URLs.

Administration¶

Administration of Weblate is done through standard Django admin interface, which is available under /admin/ URL. Once logged in as user with proper privileges, you can access it using wrench icon in top navigation:

Here you can manage objects stored in the database, such as users, translations and other settings:

In the Reports section you can check status of your site, tweak it for Production setup or manage SSH keys to access Accessing repositories.

All sections below you can manage database objects. The most interesting one is probably Weblate translations, where you can manage translatable projects, see Project configuration and Component configuration.

Another section, Weblate languages holds language defintions, see Language definitions for more details.

Adding new components¶

All translation components need to be available as VCS repositories and are organized as project/component structure.

Weblate supports wide range of translation formats (both bilingual and monolingua) supported by translate toolkit, see Supported formats for more information.

Adding project¶

First you have to add project, which will serve as container for all components. Usually you create one project for one piece of software or book (see Project configuration for information on individual parameters):

See also

Project configuration

Bilingual components¶

Once you have added a project, you can add translation compontents to it (see Component configuration for information on individual parameters):

See also

Monolingual components¶

For easier translating of monolingual formats, you should provide template file, which contains mapping of message IDs to source language (usually English) (see Component configuration for information on individual parameters):

See also

Amagama Translation Memory server

Project configuration¶

To add new component to translate, you need to create translation project first. The project is sort of shelf, in which real translations are folded. All components in same project share suggestions and dictionary, also the translations are automatically propagated through the all component in single project (unless disabled in component configuration).

The project has only few attributes giving translators information about project:

Project website: URL where translators can find more information about the project.
Mailing list: Mailing list where translators can discuss or comment translations.
Translation instructions: URL where you have more detailed instructions for translators.
Push on commit: Whether any committed changes should be automatically pushed to upstream repository.
Set Translation-Team header: Whether Weblate should manage Translation-Team header (this is GNU Gettext only feature right now).
Enable ACL: Enable per project access control, see Per project access control for more details.
Enable hooks: Whether unauthenticated Notification hooks will be enabled for this repository.
Source language: Language used for source strings in all components. Change this if you are translating from something else than English.

Note

Most of the fields can be edited by project owners or managers in the Weblate interface.

Adjusting interaction¶

There are also additional features which you can control, like automatic pushing of changes (see also Pushing changes) or maintaining of Translation-Team header.

Component configuration¶

Component is real component for translating. You enter VCS repository location and file mask which files to translate and Weblate automatically fetches the VCS and finds all matching translatable files.

Note

It is recommended to have translation components of reasonable size - split the translation by anything what makes sense in your case (individual applications or addons, book chapters or websites).

Weblate handles just fine translations with 10000 of units, but it is harder to split work and coordinate amongh translators with such big translation. Also when one translator is working on a component, this translation is locked for others, see Translation locking.

Should the language definition for translation be missing, empty definition is created and named as “cs_CZ (generated)”. You should adjust the definition and report this back to Weblate authors so that missing language can be included in next release.

The component contains all important parameters for working with VCS and getting translations out of it:

Version control system

VCS to use, see Version control integration for details.

Source code repository

VCS repository used to pull changes, see Accessing repositories for more details.

This can be either real VCS URL or weblate://project/component indicating that the repository should be shared with another component. See Weblate internal URLs for more details.

Repository push URL

Repository URL used for pushing, this is completely optional and push support will be disabled when this is empty. See Accessing repositories for more details on how to specify repository URL.

Repository browser

URL of repository browser to display source files (location where messages are used). When empty no such links will be generated.

For example on GitHub, you would use something like https://github.com/WeblateOrg/hello/blob/%(branch)s/%(file)s#L%(line)s.

Exported repository URL

URL where changes made by Weblate are exported. This is important when Continuous translation is not used or when there is need to manually merge changes. You can use Git exporter to automate this for Git repositories.

Repository branch

Which branch to checkout from the VCS and where to look for translations.

File mask

Mask of files to translate including path. It should include one * replacing language code (see Language definitions for information how this is processed). In case your repository contains more than one translation files (eg. more Gettext domains), you need to create separate component for each.

For example po/*.po or locale/*/LC_MESSAGES/django.po.

Monolingual base language file

Base file containing strings definition for Monolingual components.

Edit base file

Whether to allow editing of base file for Monolingual components.

Base file for new translations

Base file used to generate new translations, eg. .pot file with Gettext.

File format

Translation file format, see also Supported formats.

Source string bug report address

Email address used for reporting upstream bugs. This address will also receive notification about any source string comments made in Weblate.

Locked

You can lock the translation to prevent updates by users.

Allow translation propagation

You can disable propagation of translations to this component from other components within same project. This really depends on what you are translating, sometimes it’s desirable to have same string used.

It’s usually good idea to disable this for monolingual translations unless you are using same IDs across whole project.

Post-update script

One of scripts defined in POST_UPDATE_SCRIPTS which is executed after receiving update. This can be used to update the translation files.

Pre-commit script

One of scripts defined in PRE_COMMIT_SCRIPTS which is executed before commit. This can be used to generate some metadata about translation or to generate binary form of a translation.

Post-commit script

One of scripts defined in POST_COMMIT_SCRIPTS which is executed after commit. This can be used to notify external parties about the change.

Post-push script

One of scripts defined in POST_PUSH_SCRIPTS which is executed after push to remote repository. This can be used to generate notify external parties about the change in repository (i.e. create pull request).

Post-add script

One of scripts defined in POST_ADD_SCRIPTS which is executed when new translation has been added. This can be used to adjust additional files in the repository when adding new translation.

Additional commit files

Additional files to include in the commit (separated by newline), usually this one is generated by the pre commit or post add scripts described above.

Supply the %(language)s in the path like this: path/to/addditinal/%(language)s_file.example

Save translation history

Whether to store history of translation changes in database.

Suggestion voting

Enable voting for suggestions, see Suggestion voting.

Autoaccept suggestions

Automatically accept voted suggestions, see Suggestion voting.

Quality checks flags

Additional flags to pass to quality checks, see Customizing checks.

Translation license

License of this translation.

License URL

URL where users can find full text of a license.

New language

How to handle requests for creating new languages. Please note that availability of choices depends on the file format, see Supported formats.

Merge style

You can configure how the updates from upstream repository are handled. This might not be supported for some VCS. See Merge or rebase for more details.

Commit message

Message used when committing translation, see Commit message formatting.

Committer name

Name of commiter used on Weblate commits, the author will be always the real translator. On some VCS this might be not supported. Default value can be changed by DEFAULT_COMMITER_NAME.

Committer email

Email of commiter used on Weblate commits, the author will be always the real translator. On some VCS this might be not supported. Default value can be changed by DEFAULT_COMMITER_EMAIL.

Language filter

Regular expression which is used to filter translation when scanning for file mask. This can be used to limit list of languages managed by Weblate (eg. ^(cs|de|es)$ will include only those there languages. Please note that you need to list language codes as they appear in the filename.

Note

Most of the fields can be edited by project owners or managers in the Weblate interface.

Commit message formatting¶

The commit message on each commit Weblate does, it can use following format strings in the message:

%(language)s: Language code
%(language_name)s: Language name
%(component)s: Component name
%(project)s: Project name
%(url)s: Translation URL
%(total)s: Total strings count
%(fuzzy)s: Count of strings needing review
%(fuzzy_percent)s: Percent of strings needing review
%(translated)s: Translated strings count
%(translated_percent)s: Translated strings percent

Importing speed¶

Fetching VCS repository and importing translations to Weblate can be lengthy process depending on size of your translations. Here are some tips to improve this situation:

Clone Git repository in advance¶

You can put in place Git repository which will be used by Weblate. The repositories are stored in vcs directory in path defined by DATA_DIR in settings.py in <project>/<component> directories.

This can be especially useful if you already have local clone of this repository and you can use --reference option while cloning:

git clone \
    --reference /path/to/checkout \
    https://github.com/WeblateOrg/weblate.git \
    weblate/repos/project/component

Optimize configuration¶

The default configuration is useful for testing and debugging Weblate, while for production setup, you should do some adjustments. Many of them have quite big impact on performance. Please check Production setup for more details, especially:

Disable not needed checks¶

Some quality checks can be quite expensive and if you don’t need them, they can save you some time during import. See CHECK_LIST for more information how to configure this.

Automatic creation of components¶

In case you have project with dozen of translation files, you might want to import all at once. This can be achieved using import_project or import_json.

First you need to create project which will contain all components and then it’s just a matter of running import_project or import_json.

See also

Management commands

Fulltext search¶

Fulltext search is based on Whoosh. You can either allow Weblate to directly update index on every change to content or offload this to separate process by OFFLOAD_INDEXING.

The first approach (immediate updates) allows more up to date index, but suffers locking issues in some setup (eg. Apache’s mod_wsgi) and produces more fragmented index.

Offloaded indexing is always better choice for production setup - it only marks which items need to be reindexed and you need to schedule background process (update_index) to update index. This leads to faster response of the site and less fragmented index with cost that it might be slightly outdated.

Language definitions¶

In order to properly present different translation Weblate needs to know some information about used languages. Currently it comes with definitions for about 200 languages and the definition include language name, text direction, plural definitions and language code.

Parsing language codes¶

While parsing translations, Weblate attempts to map language code (usually ISO 639-1 one) to existing language object. If it can not find exact match, it tries to find best fit in existing languages (eg. it ignores default country code for given language - choosing cs instead of cs_CZ). Should this fail as well, it will create new language definition using the defaults (left to right text direction, one plural) and naming the language :guilabel:xx_XX (generated). You might want to change this in the admin interface (see Changing language defintions) and report it to our issue tracker (see Contributing).

Changing language defintions¶

You can change language definitions in the admin interface (see Administration). The Weblate languages section allows you to change or add language definitions. While editing make sure that all fields are correct (especially plurals and text direction), otherwise the translators won’t be able to properly edit those translations.

Continuous translation¶

Weblate provides you great infrastructure for translation to closely follow your development. This way translators can work on translations whole time and are not forced to translate huge amount of new texts before release.

The complete process can be described in following steps:

Developers make some changes and push them to the VCS repository.
Optionally the translation files are updated (this depends on the file format, see Why does Weblate still shows old translation strings when I’ve updated the template?).
Weblate pulls changes from the VCS repository, see Updating repositories.
Once Weblate detects changes in translations, translators will be notified based on their subscription settings.
Translators make translations using Weblate web interface.
Once translators are done, Weblate commits the changes to the local repository (see Lazy commits) and pushes them back if it has permissions to do that (see Pushing changes).

Updating repositories¶

You should set up some way how backend repositories are updated from their source. You can either use hooks (see Notification hooks) or just regularly run updategit (with selection of project or –all for updating all).

Whenever Weblate updates the repository, the Post-update script hooks are executed.

With Gettext po files, you might be often bitten by conflict in PO file headers. To avoid it, you can use shipped merge driver (examples/git-merge-gettext-po). To use it just put following configuration to your .gitconfig:

[merge "merge-gettext-po"]
  name = merge driver for gettext po files
  driver = /path/to/weblate/examples/git-merge-gettext-po %O %A %B

And enable its use by defining proper attributes in given repository (eg. in .git/info/attributes):

*.po merge=merge-gettext-po

Note

This merge driver assumes the changes in POT files always are done in branch we’re trying to merge.

Changed in version 2.9: This merge driver is automatically installed in case Weblate finds it (this currently works only for Git checkout as distutils package does not include examples).

Avoiding merge conflicts¶

To avoid merge conflicts you should control when to update translation files in upstream repository to avoid Weblate having changes on same file.

You can achieve this using Weblate’s Web API to force Weblate push all pending changes and lock translation while you are doing changes on your side.

The script for doing updates can look like:

# Lock Weblate translation
wlc lock
# Push changes from Weblate to upstream repository
wlc push
# Pull changes from upstream repository to your local copy
git pull
# Update translation files, this example is for Django
./manage.py makemessages --keep-pot -a
git commit -m 'Locale updates' -- locale
# Push changes to upstream repository
git push
# Tell Weblate to pull changes (not needed if Weblate follows your repo
# automatically)
wlc pull
# Unlock translations
wlc unlock

If you have multiple components sharing same repository, you need to lock them all separatey:

wlc lock foo/bar
wlc lock foo/baz
wlc lock foo/baj

Note

The example uses Weblate Client, which will need configuration (API keys) to be able to control Weblate remotely. You can achieve same using any HTTP client instead of wlc, eg. curl, see Weblate’s Web API.

Automatically receiving changes from GitHub¶

Weblate comes with native support for GitHub. To receive notifications on every push to GitHub repository, you just need to enable Weblate Service in the repository settings (Webhooks & Services) as shown on the image below:

To set the base URL of your Weblate installation (for example https://hosted.weblate.org) and Weblate will be notified about every push to GitHub repository:

You can also use generic Webhook, in that case the Payload URL would have to be full path to the handler, for example https://hosted.weblate.org/hooks/github/.

Automatically receiving changes from Bitbucket¶

Weblate has support for Bitbucket webhooks, all you need to do is add webhook which triggers on repository push with destination to /hooks/bitbucket/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/bitbucket/).

Automatically receiving changes from GitLab¶

Weblate has support for GitLab hooks, all you need to do is add project web hook with destination to /hooks/gitlab/ URL on your Weblate installation (for example https://hosted.weblate.org/hooks/gitlab/).

Pushing changes¶

Each project can have configured push URL and in such case Weblate offers button to push changes to remote repository in web interface. Weblate can be also configured to automatically push changes on every commit.

If you are using SSH to push, you will need to have a key without a passphrase (or use ssh-agent for Django) and the remote server needs to be verified by you via the admin interface first, otherwise pushing will fail.

The push options differ based on used Version control integration, please check that chapter for more details.

Note

You can also enable automatic pushing changes on commit, this can be done in project configuration.

See also

See Accessing repositories for setting up SSH keys and Lazy commits for information about when Weblate decides to commit changes.

Pushing changes from Hosted Weblate¶

For Hosted Weblate there is dedicated push user registered on GitHub, Bitbucket and GitLab (with username weblate and named Weblate push user). You need to add this user as a collabolator and give him permissions to push to your repository. Let us know when you’ve done so and we will enable pushing changes from Hosted Weblate for you.

Merge or rebase¶

By default Weblate merges upstream repository into its own. This is safest way in case you also access underlying repository by other means. In case you don’t need this, you can enable rebasing of changes on upstream, what will produce history with less merge commits.

Note

Rebasing can cause you troubles in case of complicated merges, so carefully consider whether you want to enable them or not.

Interacting with others¶

Weblate makes it easy to interact with others using its API.

See also

Weblate’s Web API

Lazy commits¶

Default behaviour (configured by LAZY_COMMITS) of Weblate is to group commits from same author into one if possible. This heavily reduces number of commits, however you might need to explicitly tell to do the commits in case you want to get VCS repository in sync, eg. for merge (this is by default allowed for Managers group, see Access control).

The changes are in this mode committed once any of following conditions is fulfilled:

somebody else works on the translation
merge from upstream occurs
import of translation happens
translation for a language is completed
explicit commit is requested

You can also additionally set a cron job to commit pending changes after some delay, see commit_pending and Running maintenance tasks.

Processing repository with scripts¶

You can customize way how Weblate manipulates with repository by set of scripts. These include Post-update script, Pre-commit script, Post-commit script, Post-add script and Post-push script and are briefly described in Component configuration.

Their naming quite clearly tells when given script is executed. The commit related scripts always get one parameter with full path to the translation file which has been changed.

The script is executed with the current directory set to root of VCS repository for given component.

Additionally following environment variables are available:

WL_VCS¶: Used version control system.

WL_REPO¶: Upstream repository URL.

WL_PATH¶: Absolute path to VCS repository.

WL_BRANCH¶: New in version 2.11.

Repository branch configured in the current component.

WL_FILEMASK¶: File mask for current component.

WL_TEMPLATE¶: File name of template for monolingual translations (can be empty).

WL_NEW_BASE¶: New in version 2.14.

File name of the file which is used for creating new translations (can be empty).

WL_FILE_FORMAT¶: File format used in current component.

WL_LANGUAGE¶: Language of currently processed translation (not available for component level hooks).

WL_PREVIOUS_HEAD¶: Previous HEAD on update (available only for POST_UPDATE_SCRIPTS).

Post update repository processing¶

Post update repository processing can be used to update translation files on the source change. To achieve this, please remember that Weblate only sees files which are committed to the VCS, so you need to commit changes as a part of the script.

For example with gulp you can do it using following code:

#! /bin/sh
gulp --gulpfile gulp-i18n-extract.js
git commit -m 'Update source strings' src/languages/en.lang.json

Pre commit processing of translations¶

In many cases you might want to automatically do some changes to translation before it is committed to the repository. The pre commit script is exactly the place to achieve this.

Before using any scripts, you need to list them in PRE_COMMIT_SCRIPTS configuration variable. Then you can enable them at Component configuration configuration as Pre commit script.

It is passed single parameter consisting of file name of current translation.

The script can also generate additional file to be included in the commit. This can be configured as Extra commit file at Component configuration configuration. You can use following format strings in the filename:

%(language)s: Language code

Example - generating mo files in repository¶

Allow usage of the hook in the configuration

PRE_COMMIT_SCRIPTS = (
    '/usr/share/weblate/examples/hook-generate-mo',
)

To enable it, choose now hook-generate-mo as Pre commit script. You will also want to add path to generated files to be included in VCS commit, for example po/%(language)s.mo as Extra commit file.

You can find more example scripts in examples folder within Weblate sources, their name start with hook-.

Translation process¶

Suggestion voting¶

New in version 1.6: This feature is available since Weblate 1.6.

In default Weblate setup, everybody can add suggestions and logged in users can accept them. You might however want to have more eyes on the translation and require more people to accept them. This can be achieved by suggestion voting. You can enable this on Component configuration configuration by Suggestion voting and Autoaccept suggestions. The first one enables voting feature, while the latter allows you to configure threshold at which suggestion will gets automatically accepted (this includes own vote from suggesting user).

Note

Once you enable automatic accepting, normal users lose privilege to directly save translations or accept suggestions. This can be overriden by Can override suggestion state privilege (see Access control).

You can combine these with Access control into one of following setups:

Users can suggest and vote for suggestions, limited group controls what is accepted - enable voting but not automatic accepting and remove privilege from users to save translations.
Users can suggest and vote for suggestions, which get automatically accepted once defined number of users agree on this - enable voting and set desired number of votes for automatic accepting.
Optional voting for suggestions - you can also only enable voting and in this case it can be optionally used by users when they are not sure about translation (they can suggest more of them).

Translation locking¶

To improve collaboration, it is good to prevent duplicate effort on translation. To achieve this, translation can be locked for single translator. This can be either done manually on translation page or is done automatically when somebody starts to work on translation. The automatic locking needs to be enabled using AUTO_LOCK.

The automatic lock is valid for AUTO_LOCK_TIME seconds and is automatically extended on every translation made and while user has opened translation page.

User can also explicitly lock translation for LOCK_TIME seconds.

Additional information on source strings¶

Weblate allows you to enhance translation process with information available in the translation files. This includes strings prioritization, check flags or providing visual context. All these features can be set on the Reviewing source strings:

You can access this also directly from translating interface when clicking on the edit icon next to Screenshot context, Flags or String priority:

Strings prioritization¶

New in version 2.0.

You can change string priority, strings with higher priority are offered first for translation. This can be useful for prioritizing translation of strings which are seen first by users or are otherwise important.

Quaity check flags¶

New in version 2.4.

Default set of quality check flags is determined from the translation Component configuration and the translation file. However you might want to customize this per source string and you have the option here.

See also

Quality checks

Visual context for strings¶

New in version 2.9.

You can upload screenshot showing usage of given source string within your application. This can help translators to understand where it is used and how it should be translated.

Uploaded screenshot is shown in the translation context sidebar:

In addition to Reviewing source strings, screenshots have separate management interface. You can find it under Tools menu. This allows you to upload screenshots, assign them to source strings manually or using OCR.

Once screenshot is uploaded, you will be presented following interface to manage it and assign to source strings:

Checks and fixups¶

Custom automatic fixups¶

You can also implement own automatic fixup in addition to standard ones and include them in AUTOFIX_LIST.

The automatic fixes are powerful, but can also cause damage, be careful when writing one.

For example following automatic fixup would replace every occurrence of string foo in translation with bar:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2017 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#

from weblate.trans.autofixes.base import AutoFix
from django.utils.translation import ugettext_lazy as _


class ReplaceFooWithBar(AutoFix):
    """Replace foo with bar."""

    name = _('Foobar')

    def fix_single_target(self, target, source, unit):
        if 'foo' in target:
            return target.replace('foo', 'bar'), True
        return target, False

To install custom checks, you need to provide fully-qualified path to Python class in the AUTOFIX_LIST, see Using custom modules and classes.

Customizing checks¶

Fine tuning existing checks¶

You can fine tune checks for each source string (in source strings review, see Additional information on source strings) or in the Component configuration (Quality checks flags), here is current list of flags accepted:

skip-review-flag: Ignore whether unit is marked for review when importing from VCS. This can be useful for XLIFF.
add-source-review: Whether to mark all new string in source language for review. This can be useful if you want to proofread the source language. This flag has no meaning for bilingual translations.
add-review: Whether to mark all new string for review. This can be useful if you want to proofread the translations done by developers.
rst-text: Treat text as RST document, affects Unchanged translation.
max-length:N: Limit maximal length for string to N chars, see Maximum Length
xml-text: Treat text as XML document, affects Invalid XML markup and XML tags mismatch.
python-format, c-format, php-format, python-brace-format, javascript-format: Treats all string like format strings, affects Format strings, Format strings, Format strings, Format strings, Format strings, Unchanged translation.
ignore-end-space: Skip the “Trailing space” quality check.
ignore-inconsistent: Skip the “Inconsistent” quality check.
ignore-translated: Skip the “Has been translated” quality check.
ignore-begin-newline: Skip the “Starting newline” quality check.
ignore-zero-width-space: Skip the “Zero-width space” quality check.
ignore-escaped-newline: Skip the “Mismatched n” quality check.
ignore-same: Skip the “Unchanged translation” quality check.
ignore-end-question: Skip the “Trailing question” quality check.
ignore-end-ellipsis: Skip the “Trailing ellipsis” quality check.
ignore-ellipsis: Skip the “Ellipsis” quality check.
ignore-python-brace-format: Skip the “Python brace format” quality check.
ignore-end-newline: Skip the “Trailing newline” quality check.
ignore-c-format: Skip the “C format” quality check.
ignore-javascript-format: Skip the “Javascript format” quality check.
ignore-optional-plural: Skip the “Optional plural” quality check.
ignore-end-exclamation: Skip the “Trailing exclamation” quality check.
ignore-end-colon: Skip the “Trailing colon” quality check.
ignore-xml-invalid: Skip the “Invalid XML markup” quality check.
ignore-xml-tags: Skip the “XML tags mismatch” quality check.
ignore-python-format: Skip the “Python format” quality check.
ignore-plurals: Skip the “Missing plurals” quality check.
ignore-begin-space: Skip the “Starting spaces” quality check.
ignore-bbcode: Skip the “Mismatched BBcode” quality check.
ignore-multiple-failures: Skip the “Multiple failing checks” quality check.
ignore-php-format: Skip the “PHP format” quality check.
ignore-end-stop: Skip the “Trailing stop” quality check.
ignore-angularjs-format: Skip the “AngularJS interpolation string” quality check.

Note

Generally the rule is named ignore-* for any check, using its identifier, so you can use this even for your custom checks.

These flags are understood both in Component configuration settings, per source string settings and in translation file itself (eg. in GNU Gettext).

Writing own checks¶

Weblate comes with wide range of quality checks (see Quality checks), though they might not 100% cover all you want to check. The list of performed checks can be adjusted using CHECK_LIST and you can also add custom checks. All you need to do is to subclass weblate.trans.checks.Check, set few attributes and implement either check or check_single methods (first one if you want to deal with plurals in your code, the latter one does this for you). You will find below some examples.

To install custom checks, you need to provide fully-qualified path to Python class in the CHECK_LIST, see Using custom modules and classes.

Checking translation text does not contain “foo”¶

This is pretty simple check which just checks whether translation does not contain string “foo”.

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2017 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Simple quality check example."""

from weblate.trans.checks.base import TargetCheck
from django.utils.translation import ugettext_lazy as _


class FooCheck(TargetCheck):

    # Used as identifier for check, should be unique
    # Has to be shorter than 50 chars
    check_id = 'foo'

    # Short name used to display failing check
    name = _('Foo check')

    # Description for failing check
    description = _('Your translation is foo')

    # Real check code
    def check_single(self, source, target, unit):
        return 'foo' in target

Checking Czech translation text plurals differ¶

Check using language information to verify that two plural forms in Czech language are not same.

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2017 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Quality check example for Czech plurals."""

from weblate.trans.checks.base import TargetCheck
from django.utils.translation import ugettext_lazy as _


class PluralCzechCheck(TargetCheck):

    # Used as identifier for check, should be unique
    # Has to be shorter than 50 chars
    check_id = 'foo'

    # Short name used to display failing check
    name = _('Foo check')

    # Description for failing check
    description = _('Your translation is foo')

    # Real check code
    def check_target_unit(self, sources, targets, unit):
        if self.is_language(unit, ('cs', )):
            return targets[1] == targets[2]
        return False

    def check_single(self, source, target, unit):
        """We don't check target strings here."""
        return False

Using custom modules and classes¶

You have implemented code for Custom automatic fixups or Customizing checks and now it’s time to install it into Weblate. That can be achieved by adding its fully-qualified path to Python class to appropriate settings.

This means that the module with class needs to be placed somewhere where Python interpreter can import it - either in system path (usually something like /usr/lib/python2.7/site-packages/) or in Weblate directory, which is also added to the interpreter search path.

Assuming you’ve created mahongo.py containing your custom quality check. You can place it among Weblate checks in weblate/trans/checks/ folder and then add it as following:

CHECK_LIST = (
    'weblate.trans.checks.mahongo.MahongoCheck',
)

As you can see, it’s comma separated path to your module and class name.

Alternatively, you can create proper Python package out of your customization:

Place your Python module with check into folder which will match your package name. We’re using weblate_custom_checks in following examples.
Add empty __init__.py file to the same directory. This ensures Python can import this whole package.

Write setup.py in parent directory to describe your package:

from setuptools import setup

setup(
    name = "weblate_custom_checks",
    version = "0.0.1",
    author = "Michal Cihar",
    author_email = "michal@cihar.com",
    description = "Sample Custom check for Weblate.",
    license = "BSD",
    keywords = "weblate check example",
    packages=['weblate_custom_checks'],
)

Now you can install it using python setup.py install

Once installed into system Python path, you can use it from there:

CHECK_LIST = (
    'weblate_custom_checks.mahongo.MahongoCheck',
)

Overall your module structure should look like:

weblate_custom_checks
├── setup.py
└── weblate_custom_checks
    ├── __init__.py
    └── mahongo.py

Machine translation¶

Weblate has builtin support for several machine translation services and it’s up to administrator to enable them. The services have different terms of use, so please check whether you are allowed to use them before enabling in Weblate. The individual services are enabled using MACHINE_TRANSLATION_SERVICES.

The source language can be configured at Project configuration.

Amagama¶

Special installation of tmserver run by Virtaal authors.

To enable this service, add weblate.trans.machine.tmserver.AmagamaTranslation to MACHINE_TRANSLATION_SERVICES.

See also

Apertium¶

A free/open-source machine translation platform providing translation to limited set of languages.

The recommended way how to use Apertium is to run own Apertium APy server.

Alternatively you can use https://www.apertium.org/apy if you don’t expect to make too many requests.

To enable this service, add weblate.trans.machine.apertium.ApertiumAPYTranslation to MACHINE_TRANSLATION_SERVICES.

Glosbe¶

Free dictionary and translation memory for almost every living language.

API is free to use, regarding indicated data source license. There is a limit of call that may be done from one IP in fixed period of time, to prevent from abuse.

To enable this service, add weblate.trans.machine.glosbe.GlosbeTranslation to MACHINE_TRANSLATION_SERVICES.

See also

Glosbe website

Google Translate¶

Machine translation service provided by Google.

This service uses Translation API and you need to obtain API key and enable billing on Google API console.

To enable this service, add weblate.trans.machine.google.GoogleTranslation to MACHINE_TRANSLATION_SERVICES.

Microsoft Translator¶

Deprecated since version 2.10.

Note

This service is deprecated by Microsoft as needs to be replaced by Microsoft Cognitive Services Translator.

Machine translation service provided by Microsoft, it’s known as Bing Translator as well.

You need to register at Azure market and use Client ID and secret from there.

To enable this service, add weblate.trans.machine.microsoft.MicrosoftTranslation to MACHINE_TRANSLATION_SERVICES.

Microsoft Cognitive Services Translator¶

New in version 2.10.

Note

This is replacement service for Microsoft Translator.

Machine transation service provided by Microsoft in Azure portal as a one of Cognitive Services.

You need to register at Azure portal and use key you obtain there.

To enable this service, add weblate.trans.machine.microsoft.MicrosoftCognitiveTranslation to MACHINE_TRANSLATION_SERVICES.

MyMemory¶

Huge translation memory with machine translation.

Free, anonymous usage is currently limited to 100 requests/day, or to 1000 requests/day when you provide contact email in MT_MYMEMORY_EMAIL. you can also ask them for more.

To enable this service, add weblate.trans.machine.mymemory.MyMemoryTranslation to MACHINE_TRANSLATION_SERVICES.

tmserver¶

You can run your own translation memory server which is bundled with Translate-toolkit and let Weblate talk to it. You can also use it with amaGama server, which is enhanced version of tmserver.

First you will want to import some data to the translation memory:

To enable this service, add weblate.trans.machine.tmserver.TMServerTranslation to MACHINE_TRANSLATION_SERVICES.

build_tmdb -d /var/lib/tm/db -s en -t cs locale/cs/LC_MESSAGES/django.po
build_tmdb -d /var/lib/tm/db -s en -t de locale/de/LC_MESSAGES/django.po
build_tmdb -d /var/lib/tm/db -s en -t fr locale/fr/LC_MESSAGES/django.po

Now you can start tmserver to listen to your requests:

tmserver -d /var/lib/tm/db

And configure Weblate to talk to it:

MT_TMSERVER = 'http://localhost:8888/tmserver/'

Yandex Translate¶

Machine translation service provided by Yandex.

This service uses Translation API and you need to obtain API key from Yandex.

To enable this service, add weblate.trans.machine.yandex.YandexTranslation to MACHINE_TRANSLATION_SERVICES.

See also

MT_YANDEX_KEY, Yandex Translate API

Weblate¶

Weblate can be source of machine translation as well. There are two services to provide you results - one does exact search for string, the other one finds all similar strings.

First one is useful for full string translations, the second one for finding individual phrases or words to keep the translation consistent.

To enable these services, add weblate.trans.machine.weblatetm.WeblateSimilarTranslation (for similar string matching) and/or weblate.trans.machine.weblatetm.WeblateTranslation (for exact string matching) to MACHINE_TRANSLATION_SERVICES.

Note

For similarity matching, it is recommended to have Whoosh 2.5.2 or later, earlier versions can cause infinite looks under some occasions.

Custom machine translation¶

You can also implement own machine translation services using few lines of Python code. Following example implements translation to fixed list of languages using dictionary Python module:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2017 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#
"""Machine translation example."""

from weblate.trans.machine.base import MachineTranslation
import dictionary


class SampleTranslation(MachineTranslation):
    """Sample machine translation interface."""
    name = 'Sample'

    def download_languages(self):
        """Return list of languages your machine translation supports."""
        return set(('cs',))

    def download_translations(self, source, language, text, unit, user):
        """Return tuple with translations."""
        return [(t, 100, self.name, text) for t in dictionary.translate(text)]

You can list own class in MACHINE_TRANSLATION_SERVICES and Weblate will start using that.

Configuration¶

All settings are stored in settings.py (as usual for Django).

Note

After changing any of these settings, you need to restart Weblate. In case it is run as mod_wsgi, you need to restart Apache to reload the configuration.

See also

Please check also Django’s documentation for parameters which configure Django itself.

ANONYMOUS_USER_NAME¶

User name of user for definining privileges of not logged in user.

See also

Access control

AUTH_LOCK_ATTEMPTS¶

New in version 2.14.

Maximal number of failed authentication attempts before acccount password is reset. User will not be able to log in after that using password until he asks for password reset.

Defaults to 10.

See also

Rate limiting,

AUTH_MAX_ATTEMPTS¶

New in version 2.14.

Maximal number of authentication attempts before rate limiting applies.

Defaults to 5.

AUTH_CHECK_WINDOW¶

New in version 2.14.

Length of authentication window for rate limiting in seconds.

Defaults to 300 (5 minutes).

AUTH_LOCKOUT_TIME¶

New in version 2.14.

Length of authentication lockout window after rate limit is applied.

Defaults to 600 (10 minutes).

AUTH_TOKEN_VALID¶

New in version 2.14.

Validity of token in activation and password reset mails in seconds.

Defaults to 3600 (1 hour).

AUTO_LOCK¶

Enables automatic locking of translation when somebody is working on it.

See also

Translation locking

AUTO_LOCK_TIME¶

Time in seconds for how long the automatic lock for translation will be active.

See also

Translation locking

AUTOFIX_LIST¶

List of automatic fixups to apply when saving the message.

You need to provide fully-qualified path to Python class implementing the autofixer interface.

Available fixes:

weblate.trans.autofixes.whitespace.SameBookendingWhitespace: Fixes up whitespace in beginning and end of the string to match source.
weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis: Replaces traling dots with ellipsis if source string has it.
weblate.trans.autofixes.chars.RemoveZeroSpace: Removes zero width space char if source does not contain it.
weblate.trans.autofixes.chars.RemoveControlCharS: Removes control characters if source does not contain it.

For example you can enable only few of them:

AUTOFIX_LIST = (
    'weblate.trans.autofixes.whitespace.SameBookendingWhitespace',
    'weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis',
)

BACKGROUND_HOOKS¶

Whether to run hooks in background. This is generally recommended unless you are debugging.

CHECK_LIST¶

List of quality checks to perform on translation.

You need to provide fully-qualified path to Python class implementing the check interface.

Some of the checks are not useful for all projects, so you are welcome to adjust list of performed on your installation.

For example you can enable only few of them:

CHECK_LIST = (
    'weblate.trans.checks.same.SameCheck',
    'weblate.trans.checks.chars.BeginNewlineCheck',
    'weblate.trans.checks.chars.EndNewlineCheck',
    'weblate.trans.checks.chars.BeginSpaceCheck',
    'weblate.trans.checks.chars.EndSpaceCheck',
    'weblate.trans.checks.chars.EndStopCheck',
    'weblate.trans.checks.chars.EndColonCheck',
    'weblate.trans.checks.chars.EndQuestionCheck',
    'weblate.trans.checks.chars.EndExclamationCheck',
    'weblate.trans.checks.chars.EndEllipsisCheck',
    'weblate.trans.checks.chars.EndSemicolonCheck',
    'weblate.trans.checks.chars.MaxLengthCheck',
    'weblate.trans.checks.format.PythonFormatCheck',
    'weblate.trans.checks.format.PythonBraceFormatCheck',
    'weblate.trans.checks.format.PHPFormatCheck',
    'weblate.trans.checks.format.CFormatCheck',
    'weblate.trans.checks.format.JavascriptFormatCheck',
    'weblate.trans.checks.consistency.SamePluralsCheck',
    'weblate.trans.checks.consistency.PluralsCheck',
    'weblate.trans.checks.consistency.ConsistencyCheck',
    'weblate.trans.checks.consistency.TranslatedCheck',
    'weblate.trans.checks.chars.NewlineCountingCheck',
    'weblate.trans.checks.markup.BBCodeCheck',
    'weblate.trans.checks.chars.ZeroWidthSpaceCheck',
    'weblate.trans.checks.markup.XMLTagsCheck',
    'weblate.trans.checks.source.OptionalPluralCheck',
    'weblate.trans.checks.source.EllipsisCheck',
    'weblate.trans.checks.source.MultipleFailingCheck',
)

Note

Once you change this setting the existing checks will be still stored in the database, only newly changed translation will be affected by the change. To apply change to already stored translations, you need to run updatechecks.

See also

Quality checks, Customizing checks

COMMIT_PENDING_HOURS¶

New in version 2.10.

Default interval for commiting pending changes using commit_pending.

DATA_DIR¶

New in version 2.1: In previous versions the directories were configured separately as GIT_ROOT and WHOOSH_INDEX.

Directory where Weblate stores all data. This consists of VCS repositories, fulltext index and various configuration files for external tools.

Following subdirectories usually exist:

home: Home directory used for invoking scripts.
ssh: SSH keys and configuration.
static: Default location for Django static files, specified by STATIC_ROOT.
media: Default location for Django media files, specified by MEDIA_ROOT.
vcs: Version control repositories.
whoosh: Fulltext search index using Whoosh engine.

DEFAULT_COMMITER_EMAIL¶

New in version 2.4.

Default commiter email when creating translation component (see Component configuration), defaults to noreply@weblate.org.

DEFAULT_COMMITER_NAME¶

New in version 2.4.

Default commiter name when creating translation component (see Component configuration), defaults to Weblate.

DEFAULT_TRANSLATION_PROPAGATION¶

New in version 2.5.

Default setting for translation propagation (see Component configuration), defaults to True.

See also

ENABLE_AVATARS¶

Whether to enable libravatar/gravatar based avatars for users. By default this is enabled.

The avatars are fetched and cached on the server, so there is no risk in leaking private information or slowing down the user experiences with enabling this.

See also

Avatar caching, Avatars

ENABLE_HOOKS¶

Whether to enable anonymous remote hooks.

See also

Notification hooks

ENABLE_HTTPS¶

Whether to send links to the Weblate as https or http. This setting affects sent mails and generated absolute URLs.

See also

Set correct site name

GIT_ROOT¶

Deprecated since version 2.1: This setting is no longer used, use DATA_DIR instead.

Path where Weblate will store cloned VCS repositories. Defaults to repos subdirectory.

GITHUB_USERNAME¶

GitHub username that will be used to send pull requests for translation updates.

GOOGLE_ANALYTICS_ID¶

Google Analytics ID to enable monitoring of Weblate using Google Analytics.

HIDE_REPO_CREDENTIALS¶

Hide repository credentials in the web interface. In case you have repository URL with user and password, Weblate will hide it when showing it to the users.

For example instead of https://user:password@git.example.com/repo.git it will show just https://git.example.com/repo.git.

IP_BEHIND_REVERSE_PROXY¶

New in version 2.14.

Indicates whether Weblate is running behind reverse proxy.

If set to True, Weblate gets IP address from header defined by IP_BEHIND_REVERSE_PROXY. Ensure that you are actually using reverse proxy and that it sets this header, otherwise users will be able to fake the IP address.

Defaults to False.

IP_BEHIND_REVERSE_PROXY¶

New in version 2.14.

Indicates from which header Weblate should obtain IP address when IP_BEHIND_REVERSE_PROXY is enabled.

Defaults to HTTP_X_FORWARDED_FOR.

IP_PROXY_OFFSET¶

New in version 2.14.

Indicates which part of IP_BEHIND_REVERSE_PROXY is used as client IP address.

Depending on your setup, this header might consist of several IP addresses, (for example X-Forwarded-For: a, b, client-ip) and you can configure here which address from the header is client IP address.

Defaults to 0.

LAZY_COMMITS¶

Delay creating VCS commits until this is necessary. This heavily reduces number of commits generated by Weblate at expense of temporarily not being able to merge some changes as they are not yet committed.

See also

Lazy commits

LOCK_TIME¶

Time in seconds for how long the translation will be locked for single translator when locked manually.

See also

Translation locking

LOGIN_REQUIRED_URLS_EXCEPTIONS¶

List of exceptions for LOGIN_REQUIRED_URLS, in case you won’t specify this list, the default value will be used, which allows users to access login page.

Some of exceptions you might want to include:

LOGIN_REQUIRED_URLS_EXCEPTIONS = (
    r'/accounts/(.*)$', # Required for login
    r'/static/(.*)$',   # Required for development mode
    r'/widgets/(.*)$',  # Allowing public access to widgets
    r'/data/(.*)$',     # Allowing public access to data exports
    r'/hooks/(.*)$',    # Allowing public access to notification hooks
    r'/api/(.*)$',      # Allowing access to API
)

MACHINE_TRANSLATION_SERVICES¶

List of enabled machine translation services to use.

Note

Many of services need additional configuration like API keys, please check their documentation for more details.

MACHINE_TRANSLATION_SERVICES = (
    'weblate.trans.machine.apertium.ApertiumAPYTranslation',
    'weblate.trans.machine.glosbe.GlosbeTranslation',
    'weblate.trans.machine.google.GoogleTranslation',
    'weblate.trans.machine.microsoft.MicrosoftTranslation',
    'weblate.trans.machine.mymemory.MyMemoryTranslation',
    'weblate.trans.machine.tmserver.TMServerTranslation',
    'weblate.trans.machine.weblatetm.WeblateSimilarTranslation',
    'weblate.trans.machine.weblatetm.WeblateTranslation',
)

MT_APERTIUM_APY¶

URL of the Apertium APy server, see http://wiki.apertium.org/wiki/Apertium-apy

MT_APERTIUM_KEY¶

API key for Apertium Web Service, currently not used.

Not needed at all when running own Apertium APy server.

MT_GOOGLE_KEY¶

API key for Google Translate API, you can register at https://cloud.google.com/translate/docs

MT_MICROSOFT_ID¶

Cliend ID for Microsoft Translator service.

MT_MICROSOFT_SECRET¶

Client secret for Microsoft Translator service.

MT_MICROSOFT_COGNITIVE_KEY¶

Client key for Microsoft Cognitive Services Translator API.

MT_MYMEMORY_EMAIL¶

MyMemory identification email, you can get 1000 requests per day with this.

MT_MYMEMORY_KEY¶

MyMemory access key for private translation memory, use together with MT_MYMEMORY_USER.

MT_MYMEMORY_USER¶

MyMemory user id for private translation memory, use together with MT_MYMEMORY_KEY.

MT_TMSERVER¶

URL where tmserver is running.

MT_YANDEX_KEY¶

API key for Yandex Translate API, you can register at https://tech.yandex.com/translate/

NEARBY_MESSAGES¶

How many messages around current one to show during translating.

OFFLOAD_INDEXING¶

Offload updating of fulltext index to separate process. This heavily improves responsiveness of online operation on expense of slightly outdated index, which might still point to older content.

While enabling this, don’t forget scheduling runs of update_index in cron or similar tool.

This is recommended setup for production use.

See also

Fulltext search

PIWIK_SITE_ID¶

ID of a site in Piwik you want to track.

See also

PIWIK_URL

PIWIK_URL¶

URL of a Piwik installation you want to use to track Weblate users. For more information about Piwik see <https://piwik.org/>.

See also

PIWIK_SITE_ID

POST_ADD_SCRIPTS¶

New in version 2.4.

List of scripts which are allowed as post add scripts. The script needs to be later enabled in the Component configuration.

Weblate comes with few example hook scripts which you might find useful:

examples/hook-update-linguas: Updates LINGUAS file or ALL_LINGUAS in confiugure script.

See also

POST_UPDATE_SCRIPTS¶

New in version 2.3.

List of scripts which are allowed as post update scripts. The script needs to be later enabled in the Component configuration.

Weblate comes with few example hook scripts which you might find useful:

examples/hook-update-resx: Updates resx file to match template by adding new translations and removing obsolete ones.
examples/hook-cleanup-android: Removes obsolete units from Android resource strings.

See also

PRE_COMMIT_SCRIPTS¶

List of scripts which are allowed as pre commit scripts. The script needs to be later enabled in the Component configuration.

For example you can allow script which does some cleanup:

PRE_COMMIT_SCRIPTS = (
    '/usr/local/bin/cleanup-translation',
)

Weblate comes with few example hook scripts which you might find useful:

examples/hook-generate-mo: Generates MO file from a PO file
examples/hook-unwrap-po: Unwraps lines in a PO file.
examples/hook-sort-properties: Sort and cleanups Java properties file.
examples/hook-replace-single-quotes: Replaces single quotes in a file.

See also

POST_COMMIT_SCRIPTS¶

New in version 2.4.

List of scripts which are allowed as post commit scripts. The script needs to be later enabled in the Component configuration.

See also

POST_PUSH_SCRIPTS¶

New in version 2.4.

List of scripts which are allowed as post push scripts. The script needs to be later enabled in the Component configuration.

See also

Running maintenance tasks

REGISTRATION_CAPTCHA¶

A boolean (either True or False) indicating whether registration of new accounts is protected by captcha. This setting is optional, and a default of True will be assumed if it is not supplied.

If enabled the captcha is added to all pages where users enter email address:

New account registration.
Password recovery.
Adding email to an account.

REGISTRATION_OPEN¶

A boolean (either True or False) indicating whether registration of new accounts is currently permitted. This setting is optional, and a default of True will be assumed if it is not supplied.

SELF_ADVERTISEMENT¶

Enables self advertisement of Weblate in case there are no configured ads.

See also

SIMPLIFY_LANGUAGES¶

Use simple language codes for default language/country combinations. For example fr_FR translation will use fr language code. This is usually desired behavior as it simplifies listing of the languages for these default combinations.

Disable this if you are having different translations for both variants.

SITE_TITLE¶

Site title to be used in website and emails as well.

TTF_PATH¶

Path to Droid fonts used for widgets and charts.

URL_PREFIX¶

This settings allows you to run Weblate under some path (otherwise it relies on being executed from webserver root). To use this setting, you also need to configure your server to strip this prefix. For example with WSGI, this can be achieved by setting WSGIScriptAlias.

Note

This setting does not work with Django’s builtin server, you would have to adjust urls.py to contain this prefix.

WHOOSH_INDEX¶

Deprecated since version 2.1: This setting is no longer used, use DATA_DIR instead.

Directory where Whoosh fulltext indices will be stored. Defaults to whoosh-index subdirectory.

Sample configuration¶

Following example is shipped as weblate/settings_example.py with Weblate:

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2017 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <https://weblate.org/>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
#

from __future__ import unicode_literals
import platform
import os
from logging.handlers import SysLogHandler

#
# Django settings for Weblate project.
#

DEBUG = True

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

MANAGERS = ADMINS

DATABASES = {
    'default': {
        # Use 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'.
        'ENGINE': 'django.db.backends.sqlite3',
        # Database name or path to database file if using sqlite3.
        'NAME': 'weblate.db',
        # Database user, not used with sqlite3.
        'USER': 'weblate',
        # Database password, not used with sqlite3.
        'PASSWORD': 'weblate',
        # Set to empty string for localhost. Not used with sqlite3.
        'HOST': '127.0.0.1',
        # Set to empty string for default. Not used with sqlite3.
        'PORT': '',
        # Customizations for databases
        'OPTIONS': {
            # Uncomment for MySQL older than 5.7:
            # 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'"
        },
    }
}

BASE_DIR = os.path.dirname(os.path.abspath(__file__))

# Data directory
DATA_DIR = os.path.join(BASE_DIR, '..', 'data')

# Local time zone for this installation. Choices can be found here:
# http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
# although not all choices may be available on all operating systems.
# On Unix systems, a value of None will cause Django to use the same
# timezone as the operating system.
# If running in a Windows environment this must be set to the same as your
# system time zone.
TIME_ZONE = 'UTC'

# Language code for this installation. All choices can be found here:
# http://www.i18nguy.com/unicode/language-identifiers.html
LANGUAGE_CODE = 'en-us'

LANGUAGES = (
    ('az', 'Azərbaycan'),
    ('be', 'Беларуская'),
    ('be@latin', 'Biełaruskaja'),
    ('bg', 'Български'),
    ('br', 'Brezhoneg'),
    ('ca', 'Català'),
    ('cs', 'Čeština'),
    ('da', 'Dansk'),
    ('de', 'Deutsch'),
    ('en', 'English'),
    ('el', 'Ελληνικά'),
    ('es', 'Español'),
    ('fi', 'Suomi'),
    ('fr', 'Français'),
    ('fy', 'Frysk'),
    ('gl', 'Galego'),
    ('he', 'עברית'),
    ('hu', 'Magyar'),
    ('id', 'Indonesia'),
    ('it', 'Italiano'),
    ('ja', '日本語'),
    ('ko', '한국어'),
    ('ksh', 'Kölsch'),
    ('nb', 'Norsk bokmål'),
    ('nl', 'Nederlands'),
    ('pl', 'Polski'),
    ('pt', 'Português'),
    ('pt-br', 'Português brasileiro'),
    ('ru', 'Русский'),
    ('sk', 'Slovenčina'),
    ('sl', 'Slovenščina'),
    ('sr', 'Српски'),
    ('sv', 'Svenska'),
    ('tr', 'Türkçe'),
    ('uk', 'Українська'),
    ('zh-hans', '简体字'),
    ('zh-hant', '正體字'),
)

SITE_ID = 1

# If you set this to False, Django will make some optimizations so as not
# to load the internationalization machinery.
USE_I18N = True

# If you set this to False, Django will not format dates, numbers and
# calendars according to the current locale.
USE_L10N = True

# If you set this to False, Django will not use timezone-aware datetimes.
USE_TZ = True

# URL prefix to use, please see documentation for more details
URL_PREFIX = ''

# Absolute filesystem path to the directory that will hold user-uploaded files.
# Example: "/home/media/media.lawrence.com/media/"
MEDIA_ROOT = os.path.join(DATA_DIR, 'media')

# URL that handles the media served from MEDIA_ROOT. Make sure to use a
# trailing slash.
# Examples: "http://media.lawrence.com/media/", "http://example.com/media/"
MEDIA_URL = '{0}/media/'.format(URL_PREFIX)

# Absolute path to the directory static files should be collected to.
# Don't put anything in this directory yourself; store your static files
# in apps' "static/" subdirectories and in STATICFILES_DIRS.
# Example: "/home/media/media.lawrence.com/static/"
STATIC_ROOT = os.path.join(DATA_DIR, 'static')

# URL prefix for static files.
# Example: "http://media.lawrence.com/static/"
STATIC_URL = '{0}/static/'.format(URL_PREFIX)

# Additional locations of static files
STATICFILES_DIRS = (
    # Put strings here, like "/home/html/static" or "C:/www/django/static".
    # Always use forward slashes, even on Windows.
    # Don't forget to use absolute paths, not relative paths.
)

# List of finder classes that know how to find static files in
# various locations.
STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'compressor.finders.CompressorFinder',
)

# Make this unique, and don't share it with anybody.
# You can generate it using examples/generate-secret-key
SECRET_KEY = 'jm8fqjlg+5!#xu%e-oh#7!$aa7!6avf7ud*_v=chdrb9qdco6('  # noqa

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


# GitHub username for sending pull requests.
# Please see the documentation for more details.
GITHUB_USERNAME = None

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'weblate.accounts.auth.EmailAuth',
    # 'social_core.backends.google.GoogleOAuth2',
    # 'social_core.backends.github.GithubOAuth2',
    # 'social_core.backends.bitbucket.BitbucketOAuth',
    # 'social_core.backends.suse.OpenSUSEOpenId',
    # 'social_core.backends.ubuntu.UbuntuOpenId',
    # 'social_core.backends.fedora.FedoraOpenId',
    # 'social_core.backends.facebook.FacebookOAuth2',
    'weblate.accounts.auth.WeblateUserBackend',
)

# Social auth backends setup
SOCIAL_AUTH_GITHUB_KEY = ''
SOCIAL_AUTH_GITHUB_SECRET = ''
SOCIAL_AUTH_GITHUB_SCOPE = ['user:email']

SOCIAL_AUTH_BITBUCKET_KEY = ''
SOCIAL_AUTH_BITBUCKET_SECRET = ''
SOCIAL_AUTH_BITBUCKET_VERIFIED_EMAILS_ONLY = True

SOCIAL_AUTH_FACEBOOK_KEY = ''
SOCIAL_AUTH_FACEBOOK_SECRET = ''
SOCIAL_AUTH_FACEBOOK_SCOPE = ['email', 'public_profile']

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = ''
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = ''

# Social auth settings
SOCIAL_AUTH_PIPELINE = (
    'weblate.accounts.pipeline.verify_open',
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.auth_allowed',
    'social_core.pipeline.social_auth.social_user',
    'weblate.accounts.pipeline.store_params',
    'social_core.pipeline.user.get_username',
    'weblate.accounts.pipeline.require_email',
    'social_core.pipeline.mail.mail_validation',
    'weblate.accounts.pipeline.ensure_valid',
    'weblate.accounts.pipeline.reauthenticate',
    'social_core.pipeline.social_auth.associate_by_email',
    'weblate.accounts.pipeline.verify_username',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'weblate.accounts.pipeline.cleanup_next',
    'weblate.accounts.pipeline.user_full_name',
    'weblate.accounts.pipeline.store_email',
    'weblate.accounts.pipeline.notify_connect',
    'weblate.accounts.pipeline.password_reset',
)
SOCIAL_AUTH_DISCONNECT_PIPELINE = (
    'social_core.pipeline.disconnect.allowed_to_disconnect',
    'social_core.pipeline.disconnect.get_entries',
    'social_core.pipeline.disconnect.revoke_tokens',
    'weblate.accounts.pipeline.cycle_session',
    'weblate.accounts.pipeline.adjust_primary_mail',
    'weblate.accounts.pipeline.notify_disconnect',
    'social_core.pipeline.disconnect.disconnect',
    'weblate.accounts.pipeline.cleanup_next',
)

# Custom authentication strategy
SOCIAL_AUTH_STRATEGY = 'weblate.accounts.strategy.WeblateStrategy'

SOCIAL_AUTH_EMAIL_VALIDATION_FUNCTION = \
    'weblate.accounts.pipeline.send_validation'
SOCIAL_AUTH_EMAIL_VALIDATION_URL = \
    '{0}/accounts/email-sent/'.format(URL_PREFIX)
SOCIAL_AUTH_LOGIN_ERROR_URL = \
    '{0}/accounts/login/'.format(URL_PREFIX)
SOCIAL_AUTH_EMAIL_FORM_URL = \
    '{0}/accounts/email/'.format(URL_PREFIX)
SOCIAL_AUTH_NEW_ASSOCIATION_REDIRECT_URL = \
    '{0}/accounts/profile/#auth'.format(URL_PREFIX)
SOCIAL_AUTH_PROTECTED_USER_FIELDS = ('email',)
SOCIAL_AUTH_SLUGIFY_USERNAMES = True
SOCIAL_AUTH_SLUGIFY_FUNCTION = 'weblate.accounts.pipeline.slugify_username'

# Password validation configuration
AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
        'OPTIONS': {
            'min_length': 6,
        }
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
    {
        'NAME': 'weblate.accounts.password_validation.CharsPasswordValidator',
    },
]

# Middleware
MIDDLEWARE_CLASSES = (
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'weblate.accounts.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'social_django.middleware.SocialAuthExceptionMiddleware',
    'weblate.accounts.middleware.RequireLoginMiddleware',
    'weblate.middleware.SecurityMiddleware',
)

ROOT_URLCONF = 'weblate.urls'

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.admin.apps.SimpleAdminConfig',
    'django.contrib.admindocs',
    'django.contrib.sitemaps',
    'social_django',
    'crispy_forms',
    'compressor',
    'rest_framework',
    'rest_framework.authtoken',
    'weblate.trans',
    'weblate.lang',
    'weblate.permissions',
    'weblate.screenshots',
    'weblate.accounts',
    'weblate.utils',

    # Optional: Git exporter
    # 'weblate.gitexport',

    # This application has to be placed last!
    'weblate',
)

# Path to locales
LOCALE_PATHS = (os.path.join(BASE_DIR, 'locale'), )

# Custom exception reporter to include some details
DEFAULT_EXCEPTION_REPORTER_FILTER = \
    'weblate.trans.debug.WeblateExceptionReporterFilter'

# Default logging of Weblate messages
# - to syslog in production (if available)
# - otherwise to console
# - you can also choose 'logfile' to log into separate file
#   after configuring it below

# Detect if we can connect to syslog
HAVE_SYSLOG = False
if platform.system() != 'Windows':
    try:
        SysLogHandler(address='/dev/log', facility=SysLogHandler.LOG_LOCAL2)
        HAVE_SYSLOG = True
    except IOError:
        HAVE_SYSLOG = False

if DEBUG or not HAVE_SYSLOG:
    DEFAULT_LOG = 'console'
else:
    DEFAULT_LOG = 'syslog'

# A sample logging configuration. The only tangible logging
# performed by this configuration is to send an email to
# the site admins on every HTTP 500 error when DEBUG=False.
# See http://docs.djangoproject.com/en/stable/topics/logging for
# more details on how to customize your logging configuration.
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse'
        }
    },
    'formatters': {
        'syslog': {
            'format': 'weblate[%(process)d]: %(levelname)s %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
        'logfile': {
            'format': '%(asctime)s %(levelname)s %(message)s'
        },
    },
    'handlers': {
        'mail_admins': {
            'level': 'ERROR',
            'filters': ['require_debug_false'],
            'class': 'django.utils.log.AdminEmailHandler',
            'include_html': True,
        },
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'simple'
        },
        'syslog': {
            'level': 'DEBUG',
            'class': 'logging.handlers.SysLogHandler',
            'formatter': 'syslog',
            'address': '/dev/log',
            'facility': SysLogHandler.LOG_LOCAL2,
        },
        # Logging to a file
        # 'logfile': {
        #     'level':'DEBUG',
        #     'class':'logging.handlers.RotatingFileHandler',
        #     'filename': "/var/log/weblate/weblate.log",
        #     'maxBytes': 100000,
        #     'backupCount': 3,
        #     'formatter': 'logfile',
        # },
    },
    'loggers': {
        'django.request': {
            'handlers': ['mail_admins', DEFAULT_LOG],
            'level': 'ERROR',
            'propagate': True,
        },
        # Logging database queries
        # 'django.db.backends': {
        #     'handlers': [DEFAULT_LOG],
        #     'level': 'DEBUG',
        # },
        'weblate': {
            'handlers': [DEFAULT_LOG],
            'level': 'DEBUG',
        },
        # Logging VCS operations
        # 'weblate-vcs': {
        #     'handlers': [DEFAULT_LOG],
        #     'level': 'DEBUG',
        # },
        # Python Social Auth logging
        # 'social': {
        #     'handlers': [DEFAULT_LOG],
        #     'level': 'DEBUG',
        # },
    }
}

# Logging of management commands to console
if (os.environ.get('DJANGO_IS_MANAGEMENT_COMMAND', False) and
        'console' not in LOGGING['loggers']['weblate']['handlers']):
    LOGGING['loggers']['weblate']['handlers'].append('console')

# Remove syslog setup if it's not present
if not HAVE_SYSLOG:
    del LOGGING['handlers']['syslog']

# List of machine translations
# MACHINE_TRANSLATION_SERVICES = (
#     'weblate.trans.machine.apertium.ApertiumAPYTranslation',
#     'weblate.trans.machine.glosbe.GlosbeTranslation',
#     'weblate.trans.machine.google.GoogleTranslation',
#     'weblate.trans.machine.microsoft.MicrosoftCognitiveTranslation',
#     'weblate.trans.machine.mymemory.MyMemoryTranslation',
#     'weblate.trans.machine.tmserver.AmagamaTranslation',
#     'weblate.trans.machine.tmserver.TMServerTranslation',
#     'weblate.trans.machine.yandex.YandexTranslation',
#     'weblate.trans.machine.weblatetm.WeblateSimilarTranslation',
#     'weblate.trans.machine.weblatetm.WeblateTranslation',
# )

# Machine translation API keys

# URL of the Apertium APy server
MT_APERTIUM_APY = None

# Microsoft Translator service, register at
# https://datamarket.azure.com/developer/applications/
MT_MICROSOFT_ID = None
MT_MICROSOFT_SECRET = None

# Microsoft Cognitive Services Translator API, register at
# https://portal.azure.com/
MT_MICROSOFT_COGNITIVE_KEY = None

# MyMemory identification email, see
# https://mymemory.translated.net/doc/spec.php
MT_MYMEMORY_EMAIL = None

# Optional MyMemory credentials to access private translation memory
MT_MYMEMORY_USER = None
MT_MYMEMORY_KEY = None

# Google API key for Google Translate API
MT_GOOGLE_KEY = None

# API key for Yandex Translate API
MT_YANDEX_KEY = None

# tmserver URL
MT_TMSERVER = None

# Title of site to use
SITE_TITLE = 'Weblate'

# Whether site uses https
ENABLE_HTTPS = False

# Make CSRF cookie HttpOnly, see documentation for more details:
# https://docs.djangoproject.com/en/1.11/ref/settings/#csrf-cookie-httponly
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SECURE = ENABLE_HTTPS
SESSION_COOKIE_SECURE = ENABLE_HTTPS

# URL of login
LOGIN_URL = '{0}/accounts/login/'.format(URL_PREFIX)

# URL of logout
LOGOUT_URL = '{0}/accounts/logout/'.format(URL_PREFIX)

# Default location for login
LOGIN_REDIRECT_URL = '{0}/'.format(URL_PREFIX)

# Anonymous user name
ANONYMOUS_USER_NAME = 'anonymous'

# Reverse proxy settings
IP_BEHIND_REVERSE_PROXY = False
IP_PROXY_HEADER = 'HTTP_X_FORWARDED_FOR'
IP_PROXY_OFFSET = 0

# Sending HTML in mails
EMAIL_SEND_HTML = True

# Subject of emails includes site title
EMAIL_SUBJECT_PREFIX = '[{0}] '.format(SITE_TITLE)

# Enable remote hooks
ENABLE_HOOKS = True

# Whether to run hooks in background
BACKGROUND_HOOKS = True

# Number of nearby messages to show in each direction
NEARBY_MESSAGES = 5

# Enable lazy commits
LAZY_COMMITS = True

# Offload indexing
OFFLOAD_INDEXING = False

# Translation locking
AUTO_LOCK = True
AUTO_LOCK_TIME = 60
LOCK_TIME = 15 * 60

# Render forms using bootstrap
CRISPY_TEMPLATE_PACK = 'bootstrap3'

# List of quality checks
# CHECK_LIST = (
#     'weblate.trans.checks.same.SameCheck',
#     'weblate.trans.checks.chars.BeginNewlineCheck',
#     'weblate.trans.checks.chars.EndNewlineCheck',
#     'weblate.trans.checks.chars.BeginSpaceCheck',
#     'weblate.trans.checks.chars.EndSpaceCheck',
#     'weblate.trans.checks.chars.EndStopCheck',
#     'weblate.trans.checks.chars.EndColonCheck',
#     'weblate.trans.checks.chars.EndQuestionCheck',
#     'weblate.trans.checks.chars.EndExclamationCheck',
#     'weblate.trans.checks.chars.EndEllipsisCheck',
#     'weblate.trans.checks.chars.EndSemicolonCheck',
#     'weblate.trans.checks.chars.MaxLengthCheck',
#     'weblate.trans.checks.format.PythonFormatCheck',
#     'weblate.trans.checks.format.PythonBraceFormatCheck',
#     'weblate.trans.checks.format.PHPFormatCheck',
#     'weblate.trans.checks.format.CFormatCheck',
#     'weblate.trans.checks.format.JavascriptFormatCheck',
#     'weblate.trans.checks.consistency.PluralsCheck',
#     'weblate.trans.checks.consistency.SamePluralsCheck',
#     'weblate.trans.checks.consistency.ConsistencyCheck',
#     'weblate.trans.checks.consistency.TranslatedCheck',
#     'weblate.trans.checks.chars.NewlineCountingCheck',
#     'weblate.trans.checks.markup.BBCodeCheck',
#     'weblate.trans.checks.chars.ZeroWidthSpaceCheck',
#     'weblate.trans.checks.markup.XMLValidityCheck',
#     'weblate.trans.checks.markup.XMLTagsCheck',
#     'weblate.trans.checks.source.OptionalPluralCheck',
#     'weblate.trans.checks.source.EllipsisCheck',
#     'weblate.trans.checks.source.MultipleFailingCheck',
# )

# List of automatic fixups
# AUTOFIX_LIST = (
#     'weblate.trans.autofixes.whitespace.SameBookendingWhitespace',
#     'weblate.trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis',
#     'weblate.trans.autofixes.chars.RemoveZeroSpace',
#     'weblate.trans.autofixes.chars.RemoveControlChars',
# )

# List of scripts to use in custom processing
# POST_UPDATE_SCRIPTS = (
# )
# PRE_COMMIT_SCRIPTS = (
# )

# E-mail address that error messages come from.
SERVER_EMAIL = 'noreply@example.com'

# Default email address to use for various automated correspondence from
# the site managers. Used for registration emails.
DEFAULT_FROM_EMAIL = 'noreply@example.com'

# List of URLs your site is supposed to serve
ALLOWED_HOSTS = []

# Example configuration to use memcached for caching
# CACHES = {
#     'default': {
#         'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
#         'LOCATION': '127.0.0.1:11211',
#     },
#     'avatar': {
#         'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
#         'LOCATION': os.path.join(BASE_DIR, 'avatar-cache'),
#         'TIMEOUT': 3600,
#         'OPTIONS': {
#             'MAX_ENTRIES': 1000,
#         },
#     }
# }

# REST framework settings for API
REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly'
    ],
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.TokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ),
    'DEFAULT_THROTTLE_CLASSES': (
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ),
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day'
    },
    'DEFAULT_PAGINATION_CLASS': (
        'rest_framework.pagination.PageNumberPagination'
    ),
    'PAGE_SIZE': 20,
    'VIEW_DESCRIPTION_FUNCTION': 'weblate.api.views.get_view_description',
    'UNAUTHENTICATED_USER': 'weblate.accounts.models.get_anonymous',
}

# Example for restricting access to logged in users
# LOGIN_REQUIRED_URLS = (
#     r'/(.*)$',
# )

# In such case you will want to include some of the exceptions
# LOGIN_REQUIRED_URLS_EXCEPTIONS = (
#    r'/accounts/(.*)$', # Required for login
#    r'/static/(.*)$',   # Required for development mode
#    r'/widgets/(.*)$',  # Allowing public access to widgets
#    r'/data/(.*)$',     # Allowing public access to data exports
#    r'/hooks/(.*)$',    # Allowing public access to notification hooks
#    r'/api/(.*)$',      # Allowing access to API
# )

# Force sane test runner
TEST_RUNNER = 'django.test.runner.DiscoverRunner'

Management commands¶

Note

Running management commands under different user than is running your webserver can cause wrong permissions on some files, please check Filesystem permissions for more details.

Django comes with management script (available as ./manage.py in sources or installed as weblate when Weblate is installed). It provides various management commands and Weblate extends it with several additional commands.

Invoking management commands¶

As mentioned before, invocation depends on how you have installed Weblate.

If you are using source code directly (either tarball or Git checkout), the management script is ./manage.py in Weblate sources. Execution can be done as:

python ./manage.py list_versions

If you’ve istalled Weblate using PIP installer or by ./setup.py script, the weblate is installed to your path and you can use it to control Weblate:

weblate list_versions

For Docker image, the script is installed same as above, you can execute it using docker exec:

docker exec <container> weblate list_versions

With docker-compose this is quite similar, you just have to use docker-compose run:

docker-compose run <container> weblate list_versions

add_suggestions¶

manage.py add_suggesstions <project> <component> <language> <file>¶

New in version 2.5.

Imports translation from the file as a suggestions to given translation. It skips translations which are same as existing ones, only different ones are added.

--author USER@EXAMPLE.COM¶: Email of author for the suggestions. This user has to exist prior importing (you can create one in the admin interface if needed).

Example:

./manage.py --author michal@cihar.com add_suggestions weblate master cs /tmp/suggestions-cs.po

auto_translate¶

manage.py auto_translate <project> <component> <language>¶

New in version 2.5.

Performs automatic translation based on other component translations.

--source PROJECT/COMPONENT¶: Specifies component to use as source for translation. If not specified all components in the project are used.

--user USERNAME¶: Specify username who will be author of the translations. Anonymous user is used if not specified.

--overwrite¶: Whether to overwrite existing translations.

--inconsistent¶: Whether to overwrite existing translations which are inconsistent (see Inconsistent).

--add¶: Automatically add language if given translation does not exist.

Example:

./manage.py --user nijel --inconsistent --source phpmyadmin/master phpmyadmin 4-5 cs

See also

Automatic translation

changesite¶

manage.py changesite¶

New in version 2.4.

You can use this to change or display site name from command line without using admin interface.

--set-name NAME¶: Sets name for the site.

--get-name¶: Prints currently configured site name.

See also

Set correct site name

checkgit¶

manage.py checkgit <project|project/component>¶

Prints current state of backend git repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

commitgit¶

manage.py commitgit <project|project/component>¶

Commits any possible pending changes to backend git repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

commit_pending¶

manage.py commit_pending <project|project/component>¶

Commits pending changes older than given age.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

--age HOURS¶: Age in hours for committing, default value can be set by COMMIT_PENDING_HOURS.

This is most useful if executed periodically from cron or similar tool:

./manage.py commit_pending --all --age=48

cleanuptrans¶

manage.py cleanuptrans¶

Cleanups orphaned checks and translation suggestions.

See also

createadmin¶

manage.py createadmin¶

Creates admin account with random password unless it is specified.

--password PASSWORD¶: Provide password on the command line and skip generating random one.

--username USERNAME¶: Use given name instead of admin.

--email USER@EXAMPLE.COM¶: Specify admin email.

--name¶: Specify admin name (visible).

--update¶: Update existing user (you can use this to change password).

Changed in version 2.9: Added parameters --username, --email, --name and --update.

dumpuserdata¶

manage.py dumpuserdata <file.json>¶

Dumps userdata to file for later use by importuserdata

This is useful when migrating of merging Weblate instances.

import_json¶

manage.py import_json <json-file>¶

New in version 2.7.

Batch import of components based on JSON data.

The imported JSON file structure pretty much corresponds to the component object (see GET /api/components/(string:project)/(string:component)/). You always have to include fields name and filemask.

--project PROJECT¶: Specifies where the components will be imported.

--main-component COMPONENT¶: Use VCS repository from this component for all.

--ignore¶: Skip already imported components.

--update¶: Update already imported components.

Changed in version 2.9: Added parameters --ignore and --update to deal with already imported components.

Example of JSON file:

[
    {
        "slug": "po",
        "name": "Gettext PO",
        "file_format": "po",
        "filemask": "po/*.po"
    },
    {
        "name": "Android",
        "filemask": "android/values-*/strings.xml",
        "template": "android/values/strings.xml",
        "repo": "weblate://test/test"
    }
]

See also

import_project

import_project¶

manage.py import_project <project> <gitrepo> <branch> <filemask>¶

Batch imports components into project based on file mask.

<project> names an existing project, into which the components should be imported.

The <gitrepo> defines URL of Git repository to use, and <branch> the git branch. To import additional translation components, from an existing Weblate component, use a weblate://<project>/<component> URL for the <gitrepo>.

The repository is searched for directories matching a double wildcard (**) in the <filemask>. Each of these is then added as a component, named after the matched directory. Existing components will be skipped.

--name-template TEMPLATE¶: Customise the component’s name, its parameter is a python formatting string, which will expect the match from <filemask>.

--base-file-template TEMPLATE¶: Customize base file for monolingual translations.

--file-format FORMAT¶: You can also specify file format to use (see Supported formats), the default is autodetection.

--language-regex REGEX¶: You can specify language filtering (see Component configuration) by this parameter. It has to be valid regular expression.

--main-component¶: You can specify which component will be chosen as main - the one actually containing VCS repository.

--license NAME¶: Specify translation license.

--license-url URL¶: Specify translation license URL.

--vcs NAME¶: In case you need to specify version control system to use, you can do it here. The default version control is Git.

--component-regexp REGEX¶: You can override parsing of component name from matched files here. This is a regular expression which will be matched against file name (as matched by <filemask>) and has to contain named groups name and language. This can be also used for excluding files in case they do not match this expression. For example: (?P<language>.*)/(?P<name>[^-]*)\.po

--no-skip-duplicates¶: By default the import does skip already existing projects. This is to allow repeated importing of same repository. However if you want to force importing additional components even if name or slug matches existing one, you can do it by passing --no-skip-duplicates. This is generally useful for components with long names, which will get truncated on import and many of them will get same name or slug.

To give you some examples, let’s try importing two projects.

As first we import The Debian Handbook translations, where each language has separate folder with translations of each chapter:

./manage.py import_project \
    debian-handbook \
    git://anonscm.debian.org/debian-handbook/debian-handbook.git \
    squeeze/master \
    '*/**.po'

Another example can be Tanaguru tool, where we need to specify file format, base file template and has all components and translations located in single folder:

./manage.py import_project \
    --file-format=properties \
    --base-file-template=web-app/tgol-web-app/src/main/resources/i18n/%s-I18N.properties \
    tanaguru \
    https://github.com/Tanaguru/Tanaguru \
    master \
    web-app/tgol-web-app/src/main/resources/i18n/**-I18N_*.properties

Example of more complex parsing of filenames to get correct component and language out of file name like src/security/Numerous_security_holes_in_0.10.1.de.po:

./manage.py import_project \
    --component-regexp 'wiki/src/security/(?P<name>.*)\.([^.]*)\.po$' \
    tails \
    git://git.tails.boum.org/tails master \
    'wiki/src/security/**.*.po'

Filtering only translations in chosen language:

./manage import_project \
    --language-regex '^(cs|sk)$' \
    weblate \
    https://github.com/WeblateOrg/weblate.git \
    'weblate/locale/*/LC_MESSAGES/**.po'

See also

More detailed examples can be found in the Starting with internationalization chapter, alternatively you might want to use import_json.

importuserdata¶

manage.py importuserdata <file.json>¶

Imports userdata from file created by dumpuserdata

importusers¶

manage.py importusers --check <file.json>¶

Imports users from JSON dump of Django auth_users database.

--check¶: With this option it will just check whether given file can be imported and report possible conflicts on usernames or emails.

You can dump users from existing Django installation using:

./manage.py dumpdata auth.User > users.json

list_ignored_checks¶

manage.py list_ignored_checks¶

Lists most frequently ignored checks. This can be useful for tuning your setup, if users have to ignore too many of consistency checks.

list_translators¶

manage.py list_translators <project|project/component>¶

Renders the list of translators by language for the given project:

[French]
Jean Dupont <jean.dupont@example.com>
[English]
John Doe <jd@exemple.com>

--language-code¶: Use language code instead of language name in output.

You can either define which project or component to use (eg. weblate/master) or use --all to list translators from all existing components.

list_versions¶

manage.py list_versions¶

Lists versions of Weblate dependencies.

loadpo¶

manage.py loadpo <project|project/component>¶

Reloads translations from disk (eg. in case you did some updates in VCS repository).

--force¶: Force update even if the files should be up to date.

--lang LANGUAGE¶: Limit processing to single languaguage.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

lock_translation¶

manage.py lock_translation <project|project/component>¶

Locks given component for translating. This is useful in case you want to do some maintenance on underlaying repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

See also

unlock_translation

pushgit¶

manage.py pushgit <project|project/component>¶

Pushes committed changes to upstream VCS repository.

--force-commit¶: Force committing any pending changes prior to push.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

rebuild_index¶

manage.py rebuild_index <project|project/component>¶

Rebuilds index for fulltext search. This might be lengthy operation if you have huge set of translation units.

--clean¶: Removes all words from database prior updating.

--optimize¶: The index will not be processed again, only it’s content will be optimized (removing stale entries and merging possibly split index files).

See also

Fulltext search

update_index¶

manage.py update_index¶

Updates index for fulltext search when OFFLOAD_INDEXING is enabled.

It is recommended to run this frequently (eg. every 5 minutes) to have index uptodate.

unlock_translation¶

manage.py unlock_translation <project|project/component>¶

Unnocks given component for translating. This is useful in case you want to do some maintenance on underlaying repository.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

See also

lock_translation

setupgroups¶

manage.py setupgroups¶

Configures default groups and optionally assigns all users to default group.

--move¶: Assigns all users to the default group.

--no-privs-update¶: Disables update of existing groups (only adds new ones).

See also

Access control

setuplang¶

manage.py setuplang¶

Setups list of languages (it has own list and all defined in translate-toolkit).

--no-update¶: Disables update of existing languages (only adds new ones).

updatechecks¶

manage.py updatechecks <project|project/component>¶

Updates all check for all units. This could be useful only on upgrades which do major changes to checks.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

updategit¶

manage.py updategit <project|project/component>¶

Fetches remote VCS repositories and updates internal cache.

You can either define which project or component to update (eg. weblate/master) or use --all to update all existing components.

Whiteboard messages¶

You can use whiteboard messages to give some information to your translators. The message can be site-wide or targeted on translation component or language.

This can be useful for various things from announcing purpose of the website to specifying targets for translations.

The whiteboard can currently be specified only in the admin interface:

The whiteboard messages are then shown based on specified context:

No context specified

Shown on dashboard (landing page).

Project specified

Shown on project, all its components and translations.

Component specified

Shown on component and all its translations.

Language specified

Shown on language overview and all translations in this language.

You can see how it looks on the language overview page:

And on the project page:

Advertisement¶

Weblate allows you to place advertisements inside emails and web pages. You can add them in the admin interface, defining placement and timespan, when it should be shown.

Active advertisements are chosen randomly to be displayed inside defined placement.

When no advertisements are enabled, you can enable SELF_ADVERTISEMENT to show advertisements for Weblate.

Component Lists¶

Weblate allows you to specify multiple lists of components. These will then appear as options on the user dashboard, and users can pick a list to be their default view when they log in. See Dashboard to learn more about this feature.

The names and contents of component lists can be specified in the admin interface, in Component lists section. Each component list must have a name that is displayed to the user, and a slug that represents it in the URL.

Note

Since version 2.13 you can also change the dashboard settings for the anonymous user in the admin interface, this will change what dashboard is visible to unauthenticated users.

Automatic component lists¶

New in version 2.13.

Additionally you can create Automatic component list assignment rules to automatically add components to the list based on their slug. This can be useful for maintaining component lists for large installations or in case you want to have component list with all components on your Weblate installation.

Optional Weblate modules¶

Weblate comes with several optional modules which might be useful for your setup.

Git exporter¶

New in version 2.10.

The Git exporter provides you read only access to underlaying Git repository using http.

Installation¶

To install, simply add weblate.gitexport to installed applications in settings.py:

INSTALLED_APPS += (
    'weblate.gitexport',
)

After installing you need to migrate your database, so that existing repositories are properly exported:

./manage.py migrate

Usage¶

The module automatically hooks into Weblate and sets exported repository URL in the Component configuration. The repositories are accessible under /git/ path of the Weblate, for example https://example.org/git/weblate/master/:

git clone 'https://example.org/git/weblate/master/'

Repositories are available anonymously unless Per project access control is enabled. In that case you need to authenticate using your API token (you can obtain it in your User profile):

git clone 'https://user:KEY@example.org/git/weblate/master/'

Billing¶

New in version 2.4.

Billing module is used on Hosted Weblate and is used to define billing plans, track invoices and usage limits.

Installation¶

To install, simply add weblate.billing to installed applications in settings.py:

INSTALLED_APPS += (
    'weblate.billing',
)

This module includes additional database structures, to have them installed you should run the database migration:

./manage.py migrate

Usage¶

After installation you can control billing in the admin interface. Users with billing enabled will get new Billing tab in their User profile.

Avatars¶

Weblate comes with built in support for showing user avatars based on emails. This can be disabled using ENABLE_AVATARS. The avatars are downloaded and cached server side to reduce information leaks to the sites serving them.

Weblate currently supports two backends:

Libravatar, what is federated avatar service with fallback to Gravatar. Libravatar is used automatically when pyLibravatar is installed.
Gravatar can be also used directly by Weblate, that is used if the pyLibravatar library is not found.

See also

Avatar caching, ENABLE_AVATARS

Frequently Asked Questions¶

Configuration¶

How to create automatic workflow?¶

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

Set up your git repository to tell Weblate whenever there is any change, see Notification hooks for information how to do it.
Set push URL at your Component configuration in Weblate, this will allow Weblate to push changes to your repository.
Enable push on commit on your Project configuration in Weblate, this will make Weblate push changes to your repository whenever they are committed at Weblate.
Optionally setup cron job for commit_pending.

How to access repositories over SSH?¶

Please see Accessing repositories for information about setting up SSH keys.

How to fix merge conflicts in translations?¶

The merge conflicts happen time to time when the translation file is changed in both Weblate and upstream repository. You can usually avoid this by merging Weblate translations prior to doing some changes in the translation files (eg. before executing msgmerge). Just tell Weblate to commit all pending tranlslations (you can do it in the Repository maintenance in the Tools menu) and merge the repository (if automatic push is not enabled).

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

# Add remote
git remote add weblate https://hosted.weblate.org/git/weblate/master/

# Update remotes
git remote update

# Merge Weblate changes
git merge weblate/master

# Resolve conflicts
edit ....
git add ...
...
git commit

# Push changes to upstream respository, 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 enabled (the default behavior), the change made is automatically propagated to others. This way the 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 export Git repository weblate uses?¶

There is nothing special about the repository, it lives under DATA_DIR directory and is named as 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 git server and let it serve the repository to outside world.

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

What are options of pushing changes back upstream?¶

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

Weblate automatically pushes and merges changes (see How to create automatic workflow?)
You tell manually Weblate to push (it needs push access to upstream repository)
Somebody manually merges changes from Weblate git repository into upstream repository
Somebody rewrites history produced by Weblate (eg. by eliminating merge commits), merges changes and tells Weblate to reset contet on upstream repository.

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

How can I limit Weblate access to translations only 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 repository with your translation files.

Add this as 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 repository with your source code.
You can update the main repository by translations from Weblate by:
```
git submodule update --remote path/to/translations
```

Please consult git submodule documentation for more details.

How can I check if my Weblate is configured properly?¶

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

Why does links contain example.com as domain?¶

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

See also

Set correct site name

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

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

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

See also

Why do I get warning about not reflected changes on database migration?¶

When running ./manage.py migrate, you can get following warning:

Your models have changes that are not yet reflected in a migration, and so won't be applied.
Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.

This is expected as Weblate generates choices for some fields and Django migrations can not reflect this. You can safely ignore this warning.

Usage¶

How do I review others translations?¶

You can subscribe to any changes made in Subscriptions and then check other contributions in email.
There is review tool available at bottom of translation view, where you can choose to browse translations made by others since given date.

How do I provide feedback on source string?¶

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

How can I use existing translations while translating?¶

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

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

Does Weblate update translation files besides translations?¶

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

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

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 on your own.

See also