Pootle Documentation Release 2.8.2 Pootle contributors Sep 15, 2017 Contents 1 All you need to know 3 1.1 Features..................................................3 1.2 Installation................................................ 33 1.3 Upgrading................................................ 37 1.4 Administering a server.......................................... 41 1.5 Developers................................................ 90 1.6 Frequently Asked Questions (FAQ)................................... 123 2 Additional Notes 125 2.1 Release Notes.............................................. 125 2.2 License.................................................. 164 i ii Pootle Documentation, Release 2.8.2 Pootle is an online tool that makes the process of translating so much simpler. It allows crowd-sourced translations, easy volunteer contribution and gives statistics about the ongoing work. Pootle is built using the powerful API of the Translate Toolkit and the Django framework. If you want to know more about these, you can dive into their own documentation. • Translate Toolkit Documentation • Django Documentation Contents 1 Pootle Documentation, Release 2.8.2 2 Contents CHAPTER 1 All you need to know The following pages cover the documentation of Pootle from a wide variety of perspectives, server administrator’s, and developer’s view. 1.1 Features 1.1.1 Pootle FS Pootle FS Pootle FS is Pootle’s integration with version control plugin systems. It allows Pootle to synchronize with an ex- ternal repository containing your translations, keep them synchronised and manage and resolve any conflicts either automatically or via user input. Warning: Pootle FS is considered beta in Pootle 2.8.0. We’d love you to try it out but please be aware that if you are basing production installs on Pootle FS that you can expect changes that might require manual intervention. Aims • Allow Pootle data to be stored on version control systems • Abstract version control systems into a standard method 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 3 Pootle Documentation, Release 2.8.2 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. States 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. Actions Based on the states we can determine what actions might be applicable to the stores and files. Staging We use Pootle FS commands to stage an action. Staging is not execution of those actions but merely preparing these actions for execution. Synchronisation 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 Note: 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 we will be phasing these out in the long term to make everything use Pootle FS. You can find an outline of how to use Pootle FS on your existing Pootle projects in the adding a Pootle FS managed project instructions. Once you are familiar with Pootle FS you can start migrating your projects to Pootle FS. 4 Chapter 1. All you need to know Pootle Documentation, Release 2.8.2 Install Pootle FS plugins for VCS To work with VCS systems Pootle FS requires some additional packages and configuration. Warning: Pootle FS is considered beta in Pootle 2.8.0. We’d love you to try it out but please be aware that if you are basing production installs on Pootle FS that you can expect changes that might require manual intervention. Install the Pootle FS plugins Pootle FS provides support for different VCS systems through plugins, so in order to work with a specific VCS it is necessary to install its plugin. For examples for Git: • Install the plugin: (env) $ pip install --process-dependency-links Pootle[git] • Add the plugin to INSTALLED_APPS: INSTALLED_APPS+=['pootle_fs_git'] This is done once for the whole Pootle server. Next steps Your project is now ready to use Pootle FS with the chosen VCS systems, you can now proceed to add a Pootle FS managed project. Add a Pootle FS managed project Pootle FS can work with different VCS systems as well as with the local file system. The following steps outline the setup of a Pootle FS based project: Install Pootle FS plugins Note: Pootle FS will work out of the box when synchronizing with the local file system. If this is the case you can safely skip this step. Synchronizing against any version control system requires you add some additional packages and configuration. Create a project to be managed by Pootle FS Create a project as usual, setting the Project Tree Style to Allow Pootle FS to manage filesystems. 1.1. Features 5 Pootle Documentation, Release 2.8.2 Provide Pootle FS configuration for the project Once the project is created you need to configure Pootle FS. You can accomplish this with the command line or the web UI. The UI is by far the simplest way and is outlined here: • Click on the Filesystems link below the project edit form in the project admin UI. • Add the Backend configuration: – Set the Filesystem backend to localfs as we are working against files stored on the local filesystem. – Set the Backend URL or path to point to the translation files on Pootle’s local filesystem, e.g. /path/ to/translations/MYPROJECT/ – Set the Translation path mapping for your project, for example /<language_code>/ <dir_path>/<filename>.<ext> Note: If you are setting up Pootle FS for a VCS then configure as follows: – Set the Filesystem backend to the required VCS backend. – Set the Backend URL or path to point to the repository, e.g. [email protected]:user/repo.git 6 Chapter 1. All you need to know Pootle Documentation, Release 2.8.2 • If not all of your project’s language codes match those available in Pootle, then add language mapping configu- rations for those languages. For example match fr_FR on your filesystem to fr on Pootle. Connect Pootle FS with VCS repository Note: You can safely skip this step if you are setting up the project to synchronize with the local file system. • Create a SSH key: $ sudo -u USER-RUNNING-POOTLE ssh-keygen -b 4096 • Tell your upstream repo about the public key, allowing Pootle to be able to push to the repo. – In GitHub: * Either use the public key as a Deploy key for the repository on GitHub, * Or (preferred) add the public key to a GitHub user’s SSH and GPG Keys. In most cases you want to create a specific Pootle GitHub user. Pull the translations into Pootle Once the project is created and properly set up we can pull the translations into Pootle: (env) $ pootle fs state MYPROJECT (env) $ pootle fs add MYPROJECT (env) $ pootle fs sync MYPROJECT Next steps Your project is now ready to use Pootle FS. In order to keep Pootle and the filesystem or VCS synchronised you will need to learn how to use Pootle FS. Migrating to Pootle FS While Pootle will continue to support update_stores and sync_stores this will eventually be deprecated. Thus it makes sense to migrate your projects to Pootle FS. These steps will convert a project currently hosted in POOTLE_TRANSLATION_DIRECTORY into a Pootle FS localfs project. Preparation 1. (optional) Disable the project to prevent translators working on the stores. You can also, quite safely, perform the migration live. 2. Run sync_stores to ensure that all translations in Pootle are on the filesystem. The filesystem and Pootle should now have exactly the same data. (env) $ pootle sync_stores --project=MYPROJECT 1.1. Features 7 Pootle Documentation, Release 2.8.2 Setup Pootle FS 1. In the Project Admin interface, change the Project Tree Style to Allow Pootle FS to manage filesystems. 2. Click on the Filesystems link below the project edit form and set the following: • Filesystem backend to localfs • Backend URL or path to the value of POOTLE_TRANSLATION_DIRECTORY + MYPROJECT, e.g. /path/to/pootle/translations/MYPROJECT • Translation path mapping to the one your project uses, or pick one of the existing Translation mapping presets. First synchronization Now that our project is setup we can initiate the first synchronization to ensure all files are tracked: (env) $ pootle fs add --force MYPROJECT (env) $ pootle fs sync MYPROJECT This will use translations from Pootle and ignore those on the filesystem. 8 Chapter 1. All you need to know Pootle Documentation, Release 2.8.2 Variations on the theme The process above outlines how you can move an update_stores project to Pootle FS on the local filesystem with Pootle winning.