Projects structure¶

Each project can contain various components. The reason for this structure is that all components in a project are expected to have a lot in common. Whenever translation is made in single component, it is automatically propagated to others within same project (this is especially useful when translating more version of same project).

Registration¶

While everybody can browse projects, view translations or suggest them, only registered users are allowed to actually save changes and are credited for every translation made.

You can register following two simple steps:

1. Fill out the registration form with your credentials
2. Activate registration by following in email you receive
3. Possibly adjust your profile to choose which languages you know

User profile¶

User profile contains your preferences, name and email. Name and email are being used in Git commits, so keep this information accurate.

Languages¶

Choose here which languages you prefer to translate. These will be offered to you on main page to have easier access to translations.

Secondary languages¶

You can define secondary languages, which will be shown you while translating together with source language. Example can be seen on following image, where Slovak language is shown as secondary:

Subscriptions¶

You can subscribe to various notifications on Subscriptions tab. You will receive notifications for selected events on chosen projects for languages you have indicated for translation (see above).

Authentication¶

On the Authentication tab you can connect various services which you can use to login into Weblate. List of services depends on Weblate configuration, but can include popular sites such as Google, Facebook, GitHub or Bitbucket.

Translation links¶

Once you navigate to a translation, you will be shown set of links which lead to translation. These are results of various checks, like untranslated or fuzzy strings. Should no other checks fire, there will be still link to all translations. Alternatively you can use search field to find translation you need to fix.

Suggestions¶

As an anonymous user, you have no other choice than making a suggestion. However if you are logged in you can still decide to make only a suggestion instead of saving translation, for example in case you are unsure about the translation and you want somebody else to review it.

Translating¶

On translate page, you are shown source string and edit area for translating. Should the translation be plural, multiple source strings and edit areas are shown, each described with label for plural form.

Any special whitespace chars are underlined in red and indicated with grey symbols. Also more than one space is underlined in red to allow translator to keep formatting.

There are various extra information which can be shown on this page. Most of them are coming from the project source code (like context, comments or where the message is being used). When you configure secondary languages in your preferences, translation to these languages will be shown.

Bellow translation can be also shown suggestions from other users, which you can accept or delete.

Plurals¶

What are plurals? Generally spoken plurals are words which take into account numeric meanings. But as you may imagine each language has it’s own definition of plurals. English, for example, supports one plural. We have a singular definition, for example “car”, which means implicit one car, and we have the plural definition, “cars” which could mean more than one car but also zero cars. Other languages like Czech or Arabic have more plurals and also the rules for plurals are different.

Weblate does have support for translating these and offers you one field to translate every plural separately. The number of fields and how it is used in the translated application depends on plural equation which is different for every language. Weblate shows the basic information, but you can find more detailed description in the Language Plural Rules from the Unicode Consortium.

Export and import¶

Weblate supports both export and import of translation files. This allows you to work offline and then merge changes back. Your changes will be merged within existing translation (even if it has been changed meanwhile).

Import method¶

You can choose how imported strings will be merged out of following options:

Add as translation

Imported translations are added as translation. This is most usual and default behavior.

Add as a suggestion

Imported translations are added as suggestions, do this when you want to review imported strings.

Add as fuzzy translation

Imported translations are added as fuzzy translations. This can be useful for review as well.

Additionally, when adding as a translation, you can choose whether to overwrite already translated strings or not.

Glossary¶

Each project can have assigned glossary for any language. This could be used for storing terminology for given project, so that translations are consistent. You can display terms from currently translated string in bottom tabs.

Managing glossaries¶

On project page, on Glossaries tab, you can find link Manage all glossaries, where you can start new glossaries or edit existing ones. Once glossary is existing, it will also show up on this tab.

On further page, you can choose which glossary to manage (all languages used in current project are shown). Following this language link will lead you to page, which can be used to edit, import or export the glossary:

Machine translation¶

Based on configuration and your language, Weblate provides buttons for following machine translation tools.

All machine translations are available on single tab on translation page.

Automatic fixups¶

In addition to Quality checks, Weblate can also automatically fix some common errors in translated strings. This can be quite powerful feature to prevent common mistakes in translations, however use it with caution as it can cause silent corruption as well.

Quality checks¶

Weblate does wide range of quality checks on messages. The following section describes them in more detail. The checks take account also special rules for different languages, so if you think the result is wrong, please report a bug.

from gettext import ngettext

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

Installing from sources¶

1. Install all required dependencies, see Requirements.

2. Grab Weblate sources (either using Git or download a tarball) and unpack them.

3. Copy weblate/settings_example.py to weblate/settings.py and adjust it to match your setup. You will at least need to configure database connection (possibly adding user and creating the database). Check Configuration for Weblate specific configuration options.

4. Build Django tables and initial data:

   ./manage.py syncdb
   ./manage.py migrate
   ./scripts/generate-locales # If you are using Git checkout
   

5. Configure webserver to serve Weblate, see Running server.

Using prebuilt appliance¶

1. Download the appliance and start it. You need to choose format depending on your target environment.
2. Everything should be set up immediately after boot, though you will want to adjust some settings to improve security, see SUSE Studio appliance.

Installing on OpenShift¶

1. You can install Weblate on OpenShift PaaS directly from its git repository using the OpenShift Client Tools:

   rhc -aweblate app create -t python-2.7 --from-code https://github.com/nijel/weblate.git#weblate-2.0 --no-git
   

2. After installation everything should be preconfigured and you can immediately start to add a translation project as described below. For more information, including on how to retrieve the generated admin password, see Weblate on OpenShift.

Adding translation¶

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

   All you need to specify here is project name and it’s website.

2. Create component which is the real object for translating - it points to Git repository and selects which files to translate. See Component for more details.

   The important fields here being component name, Git repository address and mask for finding translatable files. Weblate supports wide range of formats including Gettext PO files, Android resource strings, OS X string properties, Java properties or Qt Linguist files, see Supported formats for more details.

3. Once above is completed (it can be lengthy process depending on size of your Git repository and number of messages to translate), you can start translating.

Requirements¶

Python (2.7)

https://www.python.org/

Django (>= 1.6)

https://www.djangoproject.com/

Translate-toolkit (>= 1.9.0, 1.10.0 or newer strongly recommended)

http://toolkit.translatehouse.org/

Git (>= 1.6)

http://git-scm.com/

python-social-auth (>= 0.2.0)

http://psa.matiasaguirre.net/

Whoosh (>= 2.5, 2.5.2 is recommended)

http://bitbucket.org/mchaput/whoosh/

PIL or Pillow library

https://python-pillow.github.io/

lxml (>= 3.1.0)

http://lxml.de/

South (>= 1.0) (needed for Django < 1.7)

http://south.aeracode.org/

dateutil

http://labix.org/python-dateutil

libravatar (optional for federated avatar support)

https://pypi.python.org/pypi/pyLibravatar

PyICU (optional for proper sorting of strings)

https://pypi.python.org/pypi/PyICU

babel (optional for Android resources support)

http://babel.pocoo.org/

Database backend

Any database supported in Django will work, check their documentation for more details.

apt-get install python-django translate-toolkit \
    python-whoosh python-pil python-django-south python-libravatar \
    python-pyicu python-babel

# Optional for database backend

apt-get install python-mysqldb   # For MySQL
apt-get install python-psycopg2  # For PostgreSQL

# Dependencies for python-social-auth

apt-get install python-requests-oauthlib python-six python-openid

pip install python-social-auth

zypper install python-Django python-icu translate-toolkit \
    python-Whoosh python-Pillow python-South python-python-social-auth \
    python-babel

export PYTHONPATH="/usr/local/lib/python2.7/site-packages:$PYTHONPATH"

pip install -r requirements.txt

pip install -r requirements-optional.txt

apt-get install libxml2-dev libxslt-dev libfreetype6-dev python-dev

zypper install libxslt-devel libxml2-devel freetype-devel python-devel

Filesystem permissions¶

Weblate process needs to be able to read and write to two directories where it keeps data. The GIT_ROOT is used for storing Git repositories and WHOOSH_INDEX is used for fulltext search data.

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

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

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

Installation¶

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

ADMINS

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

See also

https://docs.djangoproject.com/en/1.6/ref/settings/#admins

ALLOWED_HOSTS

If you are running Django 1.5 or newer, you need to set this to list of hosts your site is supposed to serve. For example:

ALLOWED_HOSTS = ['demo.weblate.org']

See also

https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-ALLOWED_HOSTS

DATABASES

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

Note

When using MySQL, don’t forget to create database with UTF-8 encoding:

CREATE DATABASE <dbname> CHARACTER SET utf8;

See also

https://docs.djangoproject.com/en/1.6/ref/settings/#databases, https://docs.djangoproject.com/en/1.6/ref/databases/

DEBUG

Disable this for production server. With debug mode enabled, Django will show backtraces in case of error to users, when you disable it, errors will go by email to ADMINS (see above).

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

See also

https://docs.djangoproject.com/en/1.6/ref/settings/#debug

DEFAULT_FROM_EMAIL

Email sender address for outgoing email, for example registration emails.

See also

DEFAULT_FROM_EMAIL documentation

SECRET_KEY

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

SERVER_EMAIL

Email used as sender address for sending emails to administrator, for example notifications on failed merge.

See also

SERVER_EMAIL documentation

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

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

You should also login to admin interface (on /admin/ URL) and adjust default site name to match your domain.

Production setup¶

For production setup you should do following adjustments:

DEBUG = False

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

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'weblate',
        'USER': 'weblate',
        'PASSWORD': 'weblate',
        'HOST': '127.0.0.1',
        'PORT': '',
    }
}

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '127.0.0.1:11211',
    }
}

CACHES = {
    'default': {
        # Default caching backend setup, see above
        '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': 604800,
        'OPTIONS': {
            'MAX_ENTRIES': 1000,
        },
    }

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

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

TEMPLATE_LOADERS = (
    ('django.template.loaders.cached.Loader', (
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    )),
)

Running server¶

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

For testing purposes, you can use Django builtin web server:

./manage.py runserver

fastcgi.server = (
    "/weblate.fcgi" => (
        "main" => (
            "socket" => "/var/run/django/weblate.socket",
            "check-local" => "disable",
        )
    ),
)
alias.url = (
    "/media" => "/var/lib/django/weblate/weblate/media/",
    "/static/admin" => "/usr/share/pyshared/django/contrib/admin/static/admin/",
)

url.rewrite-once = (
    "^(/*media.*)$" => "$1",
    "^(/*static.*)$" => "$1",
    "^/*favicon\.ico$" => "/media/favicon.ico",
    "^/*robots\.txt$" => "/media/robots.txt",
    "^(/.*)$" => "/weblate.fcgi$1",
)

expire.url                  = (
    "/media/" => "access 1 months",
    "/static/" => "access 1 months",
    "/favicon.ico" => "access 1 months",
)

#
# VirtualHost for weblate
#
WSGIPythonPath /usr/share/weblate
<VirtualHost *:80>
    ServerAdmin admin@image.weblate.org
    ServerName image.weblate.org

    DocumentRoot /usr/share/weblate/weblate/media/

    Alias /robots.txt /usr/share/weblate/weblate/media/robots.txt
    Alias /favicon.ico /usr/share/weblate/weblate/media/favicon.ico

    Alias /media/ /usr/share/weblate/weblate/media/
    Alias /doc/ /usr/share/doc/packages/weblate/html/
    Alias /static/admin /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/

    <Directory /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/>
        Order deny,allow
        Allow from all
    </Directory>

    <Directory /usr/share/weblate/weblate/media/>
        Order deny,allow
        Allow from all
    </Directory>

    <Directory /usr/share/doc/packages/weblate/html/>
        Order deny,allow
        Allow from all
    </Directory>

    <Directory /usr/share/weblate/weblate/examples/>
        Order deny,allow
        Allow from all
    </Directory>

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

    <Directory /usr/share/weblate/weblate>
        <Files wsgi.py>
        Order deny,allow
        Allow from all
        </Files>
    </Directory>

</VirtualHost>

server {
	listen 80;
	server_name weblate;
	root /path/to/weblate/weblate;

	location /favicon.ico {
		alias /path/to/weblate/weblate/media/favicon.ico;
		expires 30d;
	}

	location /media/ {
		alias /path/to/weblate/weblate/media/;
		expires 30d;
	}

	location /robots.txt {
		alias /path/to/weblate/weblate/media/robots.txt;
		expires 30d;
	}

	location /static/admin/ {
		alias /usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/;
		expires 30d;
	}

	location / {
		include uwsgi_params;
        # Needed for long running operations in admin interface
        uwsgi_read_timeout 3600;
		uwsgi_pass 127.0.0.1:8080;
	}
}

[uwsgi]
plugins       = python
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /path/to/weblate/weblate/wsgi.py
python-path   = /path/to/weblate
# Needed in you want to use SSH keys
unenv         = HOME
# Needed for OAuth/OpenID
buffer-size   = 8192
# Increase number of workers for heavily loaded sites
#workers       = 6
# Needed for background processing
enable-threads = true

# Example Apache configuration for running Weblate under /weblate path

# Path to Weblate code
WSGIPythonPath /usr/share/weblate

# Path to Weblate WSGI handler
WSGIScriptAlias /weblate "/usr/share/weblate/weblate/wsgi.py"

# Aliases to serve media and static files
Alias /weblate/media/ /usr/share/weblate/weblate/media/
Alias /static/admin /usr/lib/python2.7/site-packages/django/contrib/admin/static/admin/

URL_PREFIX = '/weblate'

SUSE Studio appliance¶

Weblate appliance provides preconfigured Weblate running with MySQL database as backend and Apache as web server. It is provided in many formats suitable for any form of virtualization, cloud or hardware installation.

It comes with standard set of passwords you will want to change:

The appliance is built using SUSE Studio and is based on openSUSE 12.3.

You should also adjust some settings to match your environment, namely:

• Disable debug mode
• Set correct site name
• Configure email addresses

Weblate on OpenShift¶

This repository contains a configuration for the OpenShift platform as a service product, which facilitates easy installation of Weblate on OpenShift Online (https://openshift.com), OpenShift Enterprise (https://www.openshift.com/products/enterprise) and OpenShift Origin (https://www.openshift.com/products/origin).

rhc -aweblate app create -t python-2.7 --from-code https://github.com/nijel/weblate.git#weblate-2.0 --no-git

rhc -aweblate ssh credentials

rhc -aweblate add-cartridge cron
rhc -aweblate app stop
rhc -aweblate app start

rhc -aweblate env set WEBLATE_PENDING_AGE=48

rhc -aweblate env set WEBLATE_ADMINS='(("John Doe", "jdoe@example.org"),)'

rhc -aweblate app stop
rhc -aweblate app start

rhc -aweblate env set WEBLATE_PRE_COMMIT_SCRIPTS='("${OPENSHIFT_DATA_DIR}/examples/hook-generate-mo",)'

rhc -aweblate ssh settings

rhc -aweblate env unset WEBLATE_ADMINS

rhc -aweblate2 app create --from-app weblate

rhc -aweblate2 ssh update https://github.com/nijel/weblate.git#weblate-2.0

rhc -aweblate2 ssh update --force https://github.com/nijel/weblate.git#weblate-2.0

Migrating Weblate to another server¶

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

Upgrading¶

./manage.py syncdb
./manage.py migrate

./manage.py setupgroups

./manage.py setuplang

ALTER TABLE `trans_subproject` ADD `template` VARCHAR(200);

./manage.py syncdb
./manage.py migrate trans 0001 --fake
./manage.py migrate accounts 0001 --fake
./manage.py migrate lang 0001 --fake

Upgrading to Django 1.7¶

Please adjust your settings.py to match several changes in the configuration (consult settings_example.py for correct values).

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 1.7 migrations and work as usual.

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.

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.

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.

# Authentication configuration
AUTHENTICATION_BACKENDS = (
    'social.backends.github.GithubOAuth2',
    'social.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']

# Using PyPI
pip install django-auth-ldap

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

# 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',
    'django.contrib.auth.backends.ModelBackend',
)

# 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
AUTH_LDAP_USER_ATTR_MAP = {
    'first_name': 'name',
    'email': 'mail',
}

Access control¶

Weblate uses privileges system based on Django. 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. The Guests groups is used for not logged in users.

Basically Users are meant as regular translators and Managers for developers who need more control over the translation - they can force committing changes to git, push changes upstream (if Weblate is configured to do so) or disable translation (eg. when there are some major changes happening upstream).

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.

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¶

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.

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

See also

Per project access control

Translation organization¶

Weblate organizes translatable content into tree like structure. The toplevel object is Project, 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, which is actually the component to translate. Here you define Git repository to use and mask of files to translate. Bellow Component there are individual translations, which are handled automatically by Weblate as the translation files (matching mask defined in Component) appear in Git repository.

Administration¶

Administration of Weblate is done through standard Django admin interface, which is available under /admin/ URL.

Adding new components¶

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

Weblate supports wide range of translation formats supported by translate toolkit, see Supported formats for more information.

Project¶

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.

Component¶

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

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 Git and getting translations out of it:

Repo

Git repository used to pull changes.

This can be either real Git URL or weblate://project/component indicating that Git repository should be shared with another component.

Push

Git URL used for pushing, this is completely optional and push support will be disabled when this is empty.

Repoweb

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/nijel/weblate-hello/blob/%(branch)s/%(file)s#L%(line)s.

Branch

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

Filemask

Mask of files to translate including path. It should include one * replacing language code. In case your Git 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.

Base file for new translations

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

Report source bugs

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.

Pre commit script

One of scripts defined in PRE_COMMIT_SCRIPTS which is executed before commit.

Extra commit file

Additional file to include in commit, usually this one is generated by pre commit script described above.

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.

Importing speed¶

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

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

Automatic creation of components¶

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

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

Accessing repositories¶

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

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.

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

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 it’s use by defining proper attributes in given repository (eg. in .git/info/attributes):

*.po merge=merge-gettext-po

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 as shown on the image below:

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

See also

POST /hooks/github/

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.

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.

Merge or rebase¶

By default Weblate merges upstream repository into it’s 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.

Interacting with others¶

Weblate makes it easy to interact with others using it’s 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 Git 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.

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 as Pre commit script.

The hook script is executed using system() call, so it is evaluated in a shell. 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. You can use following format strings in the filename:

%(language)s

Language code

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

Suggestion voting¶

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

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.

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 - 2014 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <http://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 <http://www.gnu.org/licenses/>.
#

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


class ReplaceFooWithBar(AutoFix):
    '''
    Replaces 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

Customizing checks¶

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2014 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <http://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 <http://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
    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

# -*- coding: utf-8 -*-
#
# Copyright © 2012 - 2014 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <http://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 <http://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
    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, cache_slot):
        '''
        We don't check target strings here.
        '''
        return False

Machine translation setup¶

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 langauge can be configured by SOURCE_LANGUAGE and is shared for all translations within Weblate.

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

tmserver -d /var/lib/tm/db

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

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 - 2014 Michal Čihař <michal@cihar.com>
#
# This file is part of Weblate <http://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 <http://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):
        '''
        Returns list of languages your machine translation supports.
        '''
        return set(('cs',))

    def download_translations(self, language, text, unit, request):
        '''
        Returns 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.

ANONYMOUS_USER_NAME¶

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

AUTO_LOCK¶

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

AUTO_LOCK_TIME¶

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

AUTOFIX_LIST¶

List of automatic fixups to apply when saving the message.

Available fixes:

trans.autofixes.whitespace.SameBookendingWhitespace

Fixes up whitespace in beginning and end of the string to match source.

trans.autofixes.chars.ReplaceTrailingDotsWithEllipsis

Replaces traling dots with ellipsis if source string has it.

trans.autofixes.chars.RemoveZeroSpace

Removes zero width space char 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.

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.format.CFormatCheck',
    'weblate.trans.checks.chars.ZeroWidthSpaceCheck',
)

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.

ENABLE_HOOKS¶

Whether to enable anonymous remote hooks.

ENABLE_HTTPS¶

Whether to send links to the Weblate as https or http. This setting only affects sent mails.

ENABLE_SHARING¶

Whether to show links to share translation progress on social networks.

GIT_ROOT¶

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

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.

LAZY_COMMITS¶

Delay creating Git 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.

LOCK_TIME¶

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

LOGIN_REQUIRED_URLS¶

List of URL which require login (besides standard rules built into Weblate). This allows you to password protect whole installation using:

LOGIN_REQUIRED_URLS = (
    r'/(.*)$',
)

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'/media/(.*)$',    # 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
)

MACHINE_TRANSLATION_SERVICES¶

List of enabled machine translation services to use.

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

MT_APERTIUM_KEY¶

API key for Apertium Web Service, you can register at http://api.apertium.org/register.jsp

MT_GOOGLE_KEY¶

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

MT_MICROSOFT_ID¶

Cliend ID for Microsoft Translator service.

MT_MICROSOFT_SECRET¶

Client secret for Microsoft Translator service.

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.

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.

PRE_COMMIT_SCRIPTS¶

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

For example you can allow script which does some cleanup:

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

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.

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.

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.

SOURCE_LANGUAGE¶

Source language used for translation. This is mostly useful for machine translation services.

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.

WHOOSH_INDEX¶

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

checkgit <project|project/component>¶

manage.py checkgit¶

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

manage.py commitgit¶

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

manage.py commit_pending¶

Commits pending changes older than given age (using --age parameter, defaults to 24 hours).

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

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.

createadmin¶

manage.py createadmin¶

Creates admin account with password admin.

dumpuserdata <file.json>¶

manage.py dumpuserdata¶

Dumps userdata to file for later use by importuserdata

This is useful when migrating of merging Weblate instances.

import_project <project> <gitrepo> <branch> <filemask>¶

manage.py import_project¶

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.

To customise the component’s name, use the --name-template option. Its parameter is a python formatting string, which will expect the match from <filemask>.

By format string passed by the --base-file-template option you can customize base file for monolingual translations.

You can also specify file format to use (see Supported formats) by the --file-format parameter. The default is autodetection.

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

importuserdata <file.json>¶

manage.py importuserdata¶

Imports userdata from file created by dumpuserdata

importusers <file.json>¶

manage.py importusers¶

Imports users from JSON dump of Django auth_users database.

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

manage.py list_versions¶

Lists versions of Weblate dependencies.

loadpo <project|project/component>¶

manage.py loadpo¶

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

You can use --force to force update even if the files should be up to date. Additionally you can limit languages to process with --lang.

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

lock_translation <project|project/component>¶

manage.py lock_translation¶

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.

pushgit <project|project/component>¶

manage.py pushgit¶

Pushes committed changes to upstream Git repository. With --force-commit it also commits any pending changes.

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

rebuild_index <project|project/component>¶

manage.py rebuild_index¶

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

You can use --clean to remove all words from database prior updating.

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

manage.py unlock_translation¶

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.

setupgroups¶

manage.py setupgroups¶

Configures default groups and (if called with --move) assigns all users to default group.

The option --no-update disables update of existing groups (only adds new ones).

setuplang¶

manage.py setuplang¶

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

The option --no-update disables update of existing languages (only adds new ones).

updatechecks <project|project/component>¶

manage.py updatechecks¶

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

manage.py updategit¶

Fetches remote Git 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.