legal.rst (7378B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2014-2023 Taler Systems SA 5 6 TALER is free software; you can redistribute it and/or modify it under the 7 terms of the GNU Affero General Public License as published by the Free Software 8 Foundation; either version 2.1, or (at your option) any later version. 9 10 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 13 14 You should have received a copy of the GNU Affero General Public License along with 15 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 16 17 @author Christian Grothoff 18 19 20 The service has well-known API endpoints to return its legal conditions to the 21 user in various languages and various formats. This section describes how to 22 setup and configure the legal conditions. 23 24 25 Terms of Service 26 ---------------- 27 28 The service has an endpoint "/terms" to return the terms of service (in legal 29 language) of the service operator. Client software show these terms of 30 service to the user when the user is first interacting with the service. 31 Terms of service are optional for experimental deployments, if none are 32 configured, the service will return a simple statement saying that there are 33 no terms of service available. 34 35 To configure the terms of service response, there are two options 36 in the configuration file for the service: 37 38 - ``TERMS_ETAG``: The current "Etag" to return for the terms of service. 39 This value must be changed whenever the terms of service are 40 updated. A common value to use would be a version number. 41 Note that if you change the ``TERMS_ETAG``, you MUST also provide 42 the respective files in ``TERMS_DIR`` (see below). 43 - ``TERMS_DIR``: The directory that contains the terms of service. 44 The files in the directory must be readable to the service 45 process. 46 47 48 Privacy Policy 49 -------------- 50 51 The service has an endpoint "/pp" to return the terms privacy policy (in legal 52 language) of the service operator. Clients should show the privacy policy to 53 the user when the user explicitly asks for it, but it should not be shown by 54 default. Privacy policies are optional for experimental deployments, if none 55 are configured, the service will return a simple statement saying that there 56 is no privacy policy available. 57 58 To configure the privacy policy response, there are two options 59 in the configuration file for the service: 60 61 - ``PRIVACY_ETAG``: The current "Etag" to return for the privacy policy. 62 This value must be changed whenever the privacy policy is 63 updated. A common value to use would be a version number. 64 Note that if you change the ``PRIVACY_ETAG``, you MUST also provide 65 the respective files in ``PRIVACY_DIR`` (see below). 66 - ``PRIVACY_DIR``: The directory that contains the privacy policy. 67 The files in the directory must be readable to the service 68 process. 69 70 71 Legal policies directory layout 72 ------------------------------- 73 74 The ``TERMS_DIR`` and ``PRIVACY_DIR`` directory structures must follow a 75 particular layout. You may use the same directory for both the terms of 76 service and the privacy policy, as long as you use different ETAGs. Inside of 77 the directory, there should be sub-directories using two-letter language codes 78 like "en", "de", or "jp". Each of these directories would then hold 79 translations of the current terms of service into the respective language. 80 Empty directories are permitted in case translations are not available. 81 82 Then, inside each language directory, files with the name of the value set as 83 the ``TERMS_ETAG`` or ``PRIVACY_ETAG`` must be provided. The extension of each 84 of the files should be typical for the respective mime type. The set of 85 supported mime types is currently hard-coded in the service, and includes 86 ".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present, 87 the service may show a warning on startup. 88 89 Example 90 ^^^^^^^ 91 92 A sample file structure for a ``TERMS_ETAG`` of "tos-v0" would be: 93 94 - TERMS_DIR/en/tos-v0.txt 95 - TERMS_DIR/en/tos-v0.html 96 - TERMS_DIR/en/tos-v0.pdf 97 - TERMS_DIR/en/tos-v0.epub 98 - TERMS_DIR/en/tos-v0.md 99 - TERMS_DIR/de/tos-v0.txt 100 - TERMS_DIR/de/tos-v0.html 101 - TERMS_DIR/de/tos-v0.pdf 102 - TERMS_DIR/de/tos-v0.epub 103 - TERMS_DIR/de/tos-v0.md 104 105 If the user requests an HTML format with language preferences "fr" followed by 106 "en", the service would return ``TERMS_DIR/en/tos-v0.html`` lacking a version in 107 French. 108 109 110 Generating the Legal Terms 111 -------------------------- 112 113 The ``taler-terms-generator`` script can be used to generate directories with 114 terms of service and privacy policies in multiple languages and all required 115 data formats from a single source file in ``.rst`` format and GNU gettext 116 translations in ``.po`` format. 117 118 To use the tool, you need to first write your legal conditions in English in 119 reStructuredText (rst). You should find a templates in 120 ``$PREFIX/share/terms/*.rst`` where ``$PREFIX`` is the location where you 121 installed the service to. Whenever you make substantive changes to the legal 122 terms, you must use a fresh filename and change the respective ``ETAG``. The 123 resulting file must be called ``$ETAG.rst`` and the first line of the file should be the title of the document. 124 125 Once you have written the ``$ETAG.rst`` file in English, you can 126 generate the first set of outputs: 127 128 .. code-block:: shell-session 129 130 $ taler-terms-generator -i $ETAG 131 132 Afterwards, you should find the terms in various formats for all configured 133 languages (initially only English) in ``$PREFIX/share/terms/``. The generator 134 has a few options which are documented in its man page. 135 136 137 Adding translations 138 ------------------- 139 140 Translations must be available in subdirectories 141 ``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po``. 142 To start translating, you first need to add a new 143 language: 144 145 .. code-block:: shell-session 146 147 $ taler-terms-generator -i $ETAG -l $LANGUAGE 148 149 Here, ``$LANGUAGE`` should be a two-letter language 150 code like ``de`` or ``fr``. The command will generate 151 a file ``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po`` 152 which contains each English sentence or paragraph 153 in the original document and an initially empty 154 translation. Translators should update the ``.po`` 155 file. Afterwards, simply re-run 156 157 .. code-block:: shell-session 158 159 $ taler-terms-generator -i $ETAG 160 161 to make the current translation(s) available to the 162 service. 163 164 .. note:: 165 166 You must restart the service whenever adding or updating legal documents or their translations. 167 168 169 Updating legal documents 170 ------------------------ 171 172 When making minor changes without legal implications, edit the ``.rst`` file, 173 then re-run the step to add a new language for each existing translation to 174 produce an updated ``.po`` file. Translate the sentences that have changed and 175 finally run the generator (without ``-l``) on the ETAG (``-i $ETAG``) to 176 create the final files. 177 178 When making major changes with legal implications, you should first rename (or 179 copy) the existing ``.rst`` file and the associated translation files to a new 180 unique name. Afterwards, make the major changes, update the ``.po`` files, 181 complete the translations and re-create the final files. Finally, do not 182 forget to update the ``ETAG`` configuration option to the new name and to 183 restart the service.