HOWTO.md

   1 # This file
   2
   3 This is just a braindump from Gunnar, from the Spanish translation,
   4 documenting his steps to get from the book to the source translation
   5 material. The following instructions are valid as of June 9, 2017,
   6 19:45 GMT-5, and are mainly written in order not to forget the way
   7 this was done (and in case a future version import comes up, or we
   8 write some scripts to refine the results)
   9
  10 # How is the project built?
  11
  12 How did we get the `.po` files for the project?
  13
  14 ## First, an `.odt`
  15
  16 I don't think an Open Document Text (`.odt`) file is the ideal source
  17 format for this project, but according to the conversations I've had
  18 with Sarah, probably it's the best we can do with: It is, after all,
  19 the file they worked with. I would rather start conversion from the
  20 published EPUB file, but the conversion ends up much "noisier".
  21
  22 I downloaded
  23 [the .odt file in the repository](./MadewithCreativeCommonsmostup-to-dateversion.odt)
  24 by following the link listed as
  25 [editable version of the book (GDoc)](https://docs.google.com/document/d/1c2BXTQcWZrtW99GlGmv3waXy3AVpV-Biifw4NdDwMZg/edit#heading=h.3s5bd22z8pw5).
  26 from [the book's web page](https://madewith.cc). I am not that happy
  27 about this being an _unstable_ version (it is after all termed the
  28 _most up-to-date version_).
  29
  30 ## Directory structure for the translation
  31
  32 Most translation tools based on
  33 [GNU Gettext](https://www.gnu.org/software/gettext/) use a
  34 standardized directory structure where all translations reside in the
  35 `po` directory. It can feel a bit strange here, as the whole
  36 repository is the translation itself (Gettext is often used to
  37 translate programs, not text), but it's better not to upset common
  38 practice ;-)
  39
  40 Inside the `po` directory, we have one directory per target _locale_
  41 (per target translation). The Spanish translation lives within the
  42 `po/es` directory; in case we were to require country-specific locales
  43 (I don't forsee it being the case), they would be named `po/es_MX`,
  44 `po/es_AR`, etc. This is common in languages where national variations
  45 are stronger, such as Portuguese (would probably be `po/pt_BR`
  46 vs. `po/pt_PT`).
  47
  48 ## Markdown conversion
  49
  50 Markdown is an easy to edit format, with very little markup, and
  51 supporting basic HTML tags where needed.
  52
  53 We use Pandoc to convert the `odt` file into Markdown:
  54
  55     pandoc -f odt MadewithCreativeCommonsmostup-to-dateversion.odt -t markdown > MadewithCreativeCommonsmostup-to-dateversion.md
  56
  57 We also include the source Markdown file, mostly as documentation, in
  58 the Git repository root directory.
  59
  60 ## Extracting strings for translation
  61
  62 Gettext works by presenting each particular string to be edited. We
  63 used the [PO for anything](https://po4a.alioth.debian.org/) (po4a)
  64 tool, particularly the `po4a-gettextize` tool, to analyze the Markdown
  65 file and generate the Gettext template (`.pot`):
  66
  67     po4a-gettextize -f text -m MadewithCreativeCommonsmostup-to-dateversion.md -p po/mwcc.pot -M utf-8
  68
  69 `.pot` files are the base from which to start a translation, but are
  70 not to be modified, just updated when new versions come up. We copied
  71 this `.pot` file into the Spanish directory, with a `.po` suffix, and
  72 started the translation from there:
  73
  74     cp po/mwcc.pot po/es/mwcc.po
  75
  76 Should you want to start a new translation, that's the main step to do
  77 to start from. Note that for any future updates, the `.pot` should
  78 _not_ be copied over (as that would destroy all the translation done
  79 so far), but updated using your favorite Gettext tool.
  80
  81 ## Editing the Gettext files
  82
  83 There are many tools you can use to translate this file. If you prefer
  84 to work on your client (and mainly if you expect to do a high volume
  85 of changes), we suggest you to use the `poedit` tool; we have also
  86 been accepted as a hosted project
  87 [hosted project in the Weblate online translation coordination service](https://weblate.org/projects/madewithcc). Weblate
  88 is completely based on free software tools, we invite you to get
  89 familiar with their interface.
  90
  91 ## Building the translated Markdown file
  92
  93 `po4a` provides a tool to integrate the translation back into a
  94 Markdown document, `po4a-translate`. I have only made first attempts
  95 with it, and we need to find ways to do several improvements. However,
  96 the following command will give you a good glimpse on how your
  97 finished translation looks:
  98
  99     po4a-translate -f text -m MadewithCreativeCommonsup-to-dateversion.md -p po/es/mwcc.po -l MadewithCreativeCommonsup-to-dateversion.es.md -l MadewithCreativeCommonsup-to-dateversion.es.md -L utf8 -M utf8 -k 20
 100
 101 What does it all mean?
 102
 103     -f text
 104
 105 The base format to/from which the translation is done is plain text.
 106
 107        -m MadewithCreativeCommonsup-to-dateversion.md
 108
 109 The name of your source document.
 110
 111        -p po/es/mwcc.po
 112
 113 Which translation to use. In this case, Spanish translation.
 114
 115        -l MadewithCreativeCommonsup-to-dateversion.es.md
 116
 117 Filename to use for the created translation. Do note that I'm
 118 specifying a name that implies Spanish.
 119
 120        -L utf8 -M utf8
 121
 122 Which character sets to use, both for the source and destination
 123 files.
 124
 125        -k 20
 126
 127 Minimum translation percentage for which to produce output. The
 128 default is 80% — To get a glimpse of your work in the early stages of
 129 a translation, use `-k` with a value smaller than the percentage you
 130 have achieved.