Pootle FS

Pootle FS is Pootle’s integration with version control plugin systems. It allows Pootle to synchronize with an external repository containing your translations, keep them synchronised and manage and resolve any conflicts either automatically or via user input.


  • Allow Pootle translations to be stored in version control
  • Abstract diverse version control systems into a standard set of Pootle commands across all systems
  • Ensure that we don’t lose any data
  • Ensure that changes made on Pootle and the filesystem can seamlessly move from one to the other

Core concepts

Stores and files
Pootle contains stores of translation units. The filesystem contains files.
Tracked and untracked
When a store is associated with a file, it is tracked, if it is not yet associated then it is untracked. And vice versa.
Tracked and untracked files and stores will be in various states depending on a number of things. Have they just appeared, have they changed, have they been removed, etc.
Based on the states we can determine what actions might be applicable to the stores and files.
We use Pootle FS commands to stage an action. Staging is not execution of those actions but merely preparing these actions for execution.
This is the act of executing the staged actions.

Understanding operations

At any time we are able to query the state of Pootle FS using fs state command. The results of this operation will indicate if there are any actions you need to specify to resolve any conflicts or if there are untracked files.

You specify Actions that need to be taken to resolve conflicts or to ensure that files are tracked. This could be adding a file, removing a file or merging conflicting translations. This is the process of staging actions.

The final step is to synchronise Pootle and your filesystem. This operation takes your staged actions and executes them.

What is a filesystem

A filesystem is actually itself a Pootle FS plugin. Currently two exist:

  1. localfs - allowing synchronization with the filesystem on which Pootle is running
  2. git - synchronization with a Git repository

You can write a plugin for any version control system, Pootle FS will ensure that the same commands and operations are used to ensure Pootle and your filesystem stay synchronized.

How does Pootle FS relate to update_stores/sync_stores


Read this if you have used previous versions of Pootle.

Previous versions of Pootle made use of two commands, update_stores and sync_stores, to allow translations to be pushed into Pootle or pulled from Pootle.

These two commands still exist but are now deprecated. We will be phasing these out in the long term to make everything use Pootle FS, but you can replace these commands with Pootle FS equivalents.

You can find an outline of how to use Pootle FS in the using Pootle FS instructions. If you have a existing project you want to migrate to Pootle FS please read the migrating your projects to Pootle FS instructions. You might also have an already correctly setup project that you want to integrate directly with a version control system.