[TASK] Factor out mapping definition file
[Teams/Translation.git] / README.rst
1 =========================
2 Pootle Translation Server
3 =========================
4
5 This document describes how to install a personal Pootle translation server.
6
7 Requirements
8 ============
9
10 - `Ansible <http://docs.ansible.com/>`_. We use Ansible to easily deploy Pootle and scripts to the server.
11   The deployment receipes and scripts are found in this Git project.
12
13 - Linux server. We will use a blank `Debian AMD64 <https://www.debian.org/CD/netinst/>`_ virtual
14   machine to start with. Installation was done with only a SSH server running and command :command:`sudo`
15   being available.
16
17
18 Installing Ansible
19 ------------------
20
21 Ansible is needed on a so-called "Control Machine"; that is, a computer that will control the Pootle
22 server. This is typically your personal computer.
23
24 We will install Ansible from source since this is the recommended method. Just pick your preferred
25 user directory and::
26
27     $ sudo easy_install pip
28     $ sudo pip install paramiko PyYAML Jinja2 httplib2 six
29     $ git clone git://github.com/ansible/ansible.git --recursive
30     $ cd ./ansible
31     $ source ./hacking/env-setup
32
33 Configuring Ansible
34 -------------------
35
36 Edit or create file :file:`/etc/ansible/hosts` and put a reference to your (blank) server::
37
38     [pootle]
39     192.168.81.128    ansible_ssh_user=xavier
40
41 Provisioning Pootle server
42 --------------------------
43
44 Run::
45
46     $ git clone https://git.typo3.org/Teams/Translation.git
47     $ cd Translation
48     $ ansible-playbook -s install.yml
49
50 .. note::
51     You may need to specify your password for :command:`sudo`, if Ansible fails with ``ERROR! Missing sudo password``.
52     If so, you may ask to be prompted to give it like that::
53
54             $ ansible-playbook -s install.yml --ask-sudo-pass
55
56 Administrating Pootle
57 ---------------------
58
59 In default Pootle installations, an admin account (the password matches the username) is created with
60 superuser privileges which can be used to administer the whole site.
61
62 .. caution::
63         It's highly recommended that you change the password for the default admin account on your first
64         login, or even delete the account and assign superuser rights to another user.
65
66 When logging onto your server, you are encouraged to work as user "pootle" and follow the guide::
67
68     $ sudo su - pootle
69
70 Fetching private localisation packages within TYPO3
71 ---------------------------------------------------
72
73 Once you have your private Pootle server, and use the scripts to regularly (e.g., daily) prepare
74 localisation packages, you will need to hook into TYPO3 to automatically change the mirror URL it
75 uses to fetch localisation packages so that your own server is used instead.
76
77 To do that, take your extension, and within :file:`ext_localconf.php`, add::
78
79         /** @var \TYPO3\CMS\Extbase\SignalSlot\Dispatcher $signalSlotDispatcher */
80         $signalSlotDispatcher = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Extbase\SignalSlot\Dispatcher::class);
81
82         $signalSlotDispatcher->connect(
83                 version_compare(TYPO3_version, '7.0', '<')
84                         ? 'TYPO3\\CMS\\Lang\\Service\\UpdateTranslationService'
85                         : 'TYPO3\\CMS\\Lang\\Service\\TranslationService',
86                 'postProcessMirrorUrl',
87                 'MyCompany\\MyExtension\\Slots\\CustomMirror',
88                 'postProcessMirrorUrl'
89         );
90
91 then, create file:`my_extension/Classes/Slots/CustomMirror.php`::
92
93         <?php
94         namespace MyCompany\MyExtension\Slots;
95
96         class CustomMirror {
97                 /**
98                  * Post-processes the mirror URL for a given extension key.
99                  *
100                  * @param string $extensionKey
101                  * @param string &$mirrorUrl
102                  */
103                 public function postProcessMirrorUrl($extensionKey, &$mirrorUrl) {
104                         if ($extensionKey === 'my_extension') {
105                                 $mirrorUrl = 'http://my-custom-server.example.com/l10n_ter';
106                         }
107                 }
108         }
109
110 Migrating data from production
111 ------------------------------
112
113 - Copy po files from production and deploy to new server
114 - Dump the production database
115 - Remove every database table from new Pootle server
116 - Import production database dump
117 - Run::
118
119       $ sudo -u pootle /opt/local/pootle/bin/pootle --config=/etc/pootle/pootle.conf setup
120
121 - Migrate XLIFF to global space with unique id::
122
123       $ sudo su - pootle
124           $ ~/scripts/bin/migration/1-migrate-typo3-xliff
125           $ ~/scripts/bin/migration/2-project-renamer
126
127 - Update your password to be "password"::
128
129       UPDATE auth_user SET password='sha1$b5711$bb690a5a16cff60ae3b01fa285bcb2e68cd244f7' WHERE username='admin';