Using Pootle FS¶

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 these 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 never been synced are untracked, need to be explicitly staged. Files previously synced are tracked, will be automatically staged if there are any changes. In the case of conflicts (changes both on disk and in Pootle) it is also necessary to manually stage these to resolve which version should prevail.

When staging 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 executed by using these same options on the sync command.

Syncing tracked stores or files¶

When a store and its corresponding file are tracked and previously synced, then they are automatically staged for syncing if either changes.

If both have changed then we will need to specify how to resolve the conflict.

To re-sync stores and files run:

(env) $ pootle fs sync MYPROJECT

Adding new files and stores¶

When new files appear on the filesystem that we want to bring into Pootle we use add. And when new stores have appeared on Pootle that we want to push to the filesystem we also use add:

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

Where add will stage the previously untracked files or stores. While sync will synchronize, pulling the translations in the file into the Pootle database or pushing translations from the stores in the database to files on the filesystem.

Following this the file and store are now tracked.

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.

Using the resolve command we have four possible ways to resolve such conflicts:

1. Keep the filesystem version and discard all Pootle translations
2. Keep the Pootle version and discard 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.

The default options for resolve ensure that the filesystem always wins and that translators will be given an opportunity to resolve the conflict. This ensures that changes on version control are authoritative, a fix can land there without anyone knowing Pootle is involved. It also means that we have no data loss in that any conflicts will be presented to translators as suggestions, allowing them to resolve the conflicts by reviewing the suggestions.

(env) $ pootle fs resolve --overwrite MYPROJECT
(env) $ pootle fs sync MYPROJECT

(env) $ pootle fs resolve --overwrite --pootle-wins MYPROJECT
(env) $ pootle fs sync MYPROJECT

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

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