Using Pootle FS

The task of Pootle FS is to keep the filesystem and Pootle in sync. There are scenarios where items are not in sync and Pootle FS requires your intervention, these are the commands you need to bring things back into sync and to resolve conflicts.

Pootle FS background

To clarify the terminology that we use in Pootle FS:

  • file - a translation file on disk
  • store - a translation file in the Pootle database

Files and stores are usually associated and thus we are able to keep them synchronised. But there might be files with no store (the store for a new file has not yet been created in the Pootle database), and stores with no file (the file has been removed from the filesystem).

Pootle FS works in two stages:

  1. Actions are staged. An action is chosen to resolve each issue.
  2. The system is synchronized. The staged action are actually performed.

Files that have not being synced yet are untracked, and thus they need to be explicitly staged. Files previously synced are tracked, and thus automatically staged when any changes. In case of conflict (changes both in disk and Pootle) it is also necessary to manually stage these to resolve which version should prevail.

When staging changed items it is possible to specify specific stores or files, or groups of them using the -P and -p options. It is also possible to limit which staged actions are performed by using these same options on the sync command.

Syncing tracked stores or files

When a store and corresponding file have been synced previously, they are automatically staged for syncing if either changes.

If both have changed then we will be required to specify how to resolve the conflicts.

To re-sync stores and files just run:

(env) $ pootle fs sync MYPROJECT

Pulling new files from the filesystem into Pootle

When new files appear on the filesystem that we want to bring into Pootle we use fetch:

(env) $ pootle fs fetch MYPROJECT
(env) $ pootle fs sync MYPROJECT

Where fetch will stage the previously untracked files, and sync will synchronize, pulling the translations in the file into the Pootle database.

Following this the file and store are now tracked.

Pushing new stores from Pootle to the filesystem

When new stores have appeared on Pootle that we want to push to the filesystem we use add:

(env) $ pootle fs add MYPROJECT
(env) $ pootle fs sync MYPROJECT

Where add will stage the previously untracked store, and sync will synchronize, pushing the translations in the Pootle store onto the filesystem.

Removing files or stores

A store or file can be missing from Pootle or the filesystem because it has been removed, we use rm to remove such files and stores:

(env) $ pootle fs rm MYPROJECT
(env) $ pootle fs sync MYPROJECT

This will remove the store or file, depending on whether it is the file or store that remains.

Following this there is no such file or store on the filesystem or on Pootle.

Resolving conflicts

Conflicts can occur if a tracked Pootle store and its corresponding file have both changed. They can also arise if a new Pootle store is added and a matching file has been added in the filesystem simultaneously.

There are four possible ways to resolve such conflicts:

  1. Use the filesystem version and discard all Pootle translations
  2. Use the Pootle version and ignore all filesystem translations
  3. Merge translations and for unit conflicts choose Pootle’s version and turn the filesystem version into a suggestion
  4. Merge translations and for unit conflicts choose the filesystem version and turn the Pootle translation into a suggestion

The merge options are most useful where you need translators to resolve the conflict.

Overwrite Pootle with filesystem version

You want to keep the version that is currently on the filesystem, discarding all changes in Pootle:

(env) $ pootle fs fetch --force MYPROJECT
(env) $ pootle fs sync MYPROJECT

Overwrite filesystem with Pootle version

You wish to keep the version that is currently in Pootle, discarding all changes in the filesystem:

(env) $ pootle fs add --force MYPROJECT
(env) $ pootle fs sync MYPROJECT

Use filesystem version and convert Pootle version into suggestion

To retain all translation and allow translators to resolve conflicts use merge. This will merge any non-conflicting units and convert conflicts into suggestions, by default we use filesystem translations:

(env) $ pootle fs merge MYPROJECT
(env) $ pootle fs sync MYPROJECT

The result is that all non-conflicting units have been synchronised. For any unit where both the store unit and file unit changed the translation is set to the file unit translation with the store unit translation converted into a suggestion. You can now review these suggestions to resolve the conflicts.

Use Pootle version and convert filesystem version into suggestion

To retain all translation and allow translators to resolve conflicts use merge. This will merge any non-conflicting units and convert conflicts into suggestions, the --pootle-wins option ensures that we use Pootle translations and convert filesystem translations into suggestions:

(env) $ pootle fs merge --pootle-wins MYPROJECT
(env) $ pootle fs sync MYPROJECT