Now that you have the server running, you can setup a project to translate on the server.
To simplify the example we assume that:
You need to place the translation files for your new project in a location
where Pootle can find, read and write them. Pootle uses the
POOTLE_TRANSLATION_DIRECTORY
setting to find out where translation
files are stored on the server.
Our example project uses a GNU layout.
A GNU layout means that our project contains translation files named using language codes. Within the project there are no directories, just files. There can only be a single translation file per language in a project using this layout.
This is the simplest layout possible and the reason we are using it in our example.
Below you can see an example with two projects using the GNU layout:
`-- translations
`-- project1
| `-- po
| |-- de.po
| |-- fr.po
| |-- gl.po
| |-- pt_BR.po
| `-- templates.pot
`-- project2
`-- po
|-- af.po
|-- eu.po
|-- pt_BR.po
|-- templates.pot
`-- zu.po
Among the regular translation files there are two files named
templates.pot
. These are the template (master or reference) files that
contain the original strings. Usually these files contain only English strings,
however it is much less confusing to use the term templates
than e.g.
en
or English
.
To get started, create a my-project
directory in the location pointed
to by POOTLE_TRANSLATION_DIRECTORY
and place within it the
translation files for your new project. Make sure you have a
templates.pot
among those project translation files.
Note
If you want to integrate your project with a version control system you need to install the Pootle FS plugins for the VCS and connect Pootle FS with the VCS repository before creating the project in Pootle.
At the top of the user interface, you will see your newly created administrator username. Click on it and the main top menu will be displayed, then click on Admin (highlighted in red):
Now you are in the administration interface. Go to the Projects tab and you will see a New Project button:
Click on that button and the Add Project form will be displayed. Enter the new project’s details.
Code is a unique string that identifies the project. Also you must specify the File Types used in this new project.
The Filesystem backend tells Pootle FS how to synchronize the translations
in the project. The default option is localfs
which tells to synchronize
with the disk. Other backends allow to synchronize with version control systems
and they might require the installation of additional Pootle FS plugins.
Path or URL either is a path pointing to the translation files on the disk
if you are using the localfs
Filesystem backend, or is a URL pointing
to the VCS repository. The path can be an absolute path like
/path/to/translations/my-project/
or it can use the
{POOTLE_TRANSLATION_DIRECTORY}
placeholder if you are using the localfs
Filesystem backend, like {POOTLE_TRANSLATION_DIRECTORY}my-project
(the placeholder will be transparently replaced by the value of the
POOTLE_TRANSLATION_DIRECTORY
setting). If you are using a
Filesystem backend that uses a URL instead of a Path, for example for the
Git backend, this would be like git@github.com:user/repo.git
for a
GitHub repository.
The Path mapping field specifies the project layout using a glob like
/path/to/translation/files/<language_code>/<dir_path>/<filename>.<ext>
that
must start with /
, end with .<ext>
, and contain <language_code>
(the rest of the placeholders are optional). If you are using the localfs
Filesystem backend the Path mapping will be combined with the path
specified in the Path or URL field. For other backends it will be relative
to the root of the repository. Note you can easily fill this field by selecting
one of the available Path mapping presets.
You can also provide a Full Name easily readable for humans, if not the Code will be used. You don’t need to change the rest of the fields unless you need to further customize your project.
Note
If you are creating a project that is integrated with a version control repository then configure as follows:
git@github.com:user/repo.git
for a GitHub repository.In our example set the following:
my-project
.My project
Gettext PO (po/pot)
.localfs
.{POOTLE_TRANSLATION_DIRECTORY}my-project
.GNU style
.Once you are done click on the Save button below the form to create the project and save its Pootle FS configuration.
If not all of your project’s language codes do not match those available in Pootle, then you must add language mapping configurations for those languages. You can do that by clicking on the Languages link that is displayed below your project form:
The existing languages enabled for the project are listed, including an
optional mapping to the language code used in the filesystem. In the
screenshot below you can see that fr_FR
on filesystem maps to fr
on
Pootle:
In our example this form won’t list any language, so you must add new entries for the languages that need to be mapped specifying their Filesystem language code field.
Creating the project doesn’t actually import all the translations to Pootle. To do that you need to run the following on the command line of the Pootle server:
(env) $ pootle fs fetch my-project
(env) $ pootle fs state my-project
(env) $ pootle fs add my-project
(env) $ pootle fs sync my-project
Note
Read the using Pootle FS instructions in order to learn more about Pootle FS usage.
This will import all the translations from disk into Pootle, calculate the translation statistics and calculate the quality check failures. This might take a while for a large project.
Looking at your new project you will see that Pootle has imported all the
existing translations for the existing languages that you copied to the
my-project
directory within POOTLE_TRANSLATION_DIRECTORY
.
When you want to add a new language to the project, follow these steps.
Go to your project overview and select Languages in the navigation dropdown:
Note
Alternatively you can get the same result by clicking on the Languages link that is displayed below your project form in the administration interface:
The existing languages enabled for the project are listed, including an
optional mapping to the language code used in the filesystem (in the
screenshot below you can see that fr_FR
on filesystem maps to fr
on
Pootle). In our example we are adding Arabic to the project:
When you click the Save button the new language will be added for
translation. In large projects it may take some time to create the new
translation files from the templates
.
Note
If you want to enable translation to a language that doesn’t yet exist in your Pootle instance, then you will first have to add the language in the Languages tab in the administration interface, in a similar way to creating a new project.
Once the language is created you can enable translation to that new language in any project by following the instructions above.
Whenever developers introduce new strings, deprecate older ones, or change some of them this impacts Pootle and the languages being translated.
When any of these changes occur, you will need to generate a new
templates.pot
and use it to bring the translations in Pootle up-to-date
with the new templates.
Once you have created the new templates.pot
place it within your
project’s directory in POOTLE_TRANSLATION_DIRECTORY
, replacing the
file with the same name. After that, invoke the following command which will
update the template translations in the Pootle database.
(env) $ pootle update_stores --project=my-project --language=templates
This command will ensure that new strings are added to the project and any strings which have been removed are marked as deprecated, and thus will not be available for translation.
Now each of the languages will need to be brought into sync with the template language. The first step is to save all the Pootle translations to disk:
(env) $ pootle sync_stores --project=my-project
Then update all those translations on disk against the newer templates. We recommend you to update them on disk using the pot2po command line tool because it can handle other formats besides Gettext PO.
(env) $ cd $POOTLE_TRANSLATION_DIRECTORY # Use the actual path!
(env) $ cd my-project
(env) $ pot2po -t af.po templates.pot af.po # Repeat for each language by changing the language code.
Note
To preserve the existing translations we pass the previous
translation file to the -t
option.
When all the languages in the project have been updated you can push them back to Pootle:
(env) $ pootle update_stores --project=my-project
Note
If your project languages contain many translations you might want to perform the update against newer templates on a language by language basis.