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 ## Quick and easy: How to rebuild the sources
  49
  50 You don't really need to follow this script; it's all scripted in a
  51 `Makefile`. To update the `.pot` (translation template) file, just
  52 run:
  53
  54     `make pot`
  55
  56 That is enough to get you to the _Editing the Gettext files_ section.
  57
  58 ## Markdown conversion
  59
  60 Markdown is an easy to edit format, with very little markup, and
  61 supporting basic HTML tags where needed.
  62
  63 We use Pandoc to convert the `odt` file into Markdown:
  64
  65     pandoc -f odt MadewithCreativeCommonsmostup-to-dateversion.odt -t markdown > MadewithCreativeCommonsmostup-to-dateversion.md
  66
  67 We also include the source Markdown file, mostly as documentation, in
  68 the Git repository root directory.
  69
  70 ### Markdown fixup
  71
  72 The generated Markdown file is correct, but somewhat _dirty_. I came
  73 up with a quick-and-dirty(er) script to fix several issues,
  74 `fixup.rb`, and intend to update it as needed:
  75
  76     ruby fixup.rb source.md dest.md
  77
  78 I still need to add to this fixup the needed markup so that the built
  79 material reflects the book's structure. It will happen :-) It will, of
  80 course, happen earlier if you send me some patches!
  81
  82 ## Extracting strings for translation
  83
  84 Gettext works by presenting each particular string to be edited. We
  85 used the [PO for anything](https://po4a.alioth.debian.org/) (po4a)
  86 tool, particularly the `po4a-gettextize` tool, to analyze the Markdown
  87 file and generate the Gettext template (`.pot`):
  88
  89     po4a-gettextize -f text -m MadewithCreativeCommonsmostup-to-dateversion.md -p po/mwcc.pot -M utf-8
  90
  91 `.pot` files are the base from which to start a translation, but are
  92 not to be modified, just updated when new versions come up. We copied
  93 this `.pot` file into the Spanish directory, with a `.po` suffix, and
  94 started the translation from there:
  95
  96     cp po/mwcc.pot po/es/mwcc.po
  97
  98 Should you want to start a new translation, that's the main step to do
  99 to start from. Note that for any future updates, the `.pot` should
 100 _not_ be copied over (as that would destroy all the translation done
 101 so far), but updated using your favorite Gettext tool.
 102
 103 ## Editing the Gettext files
 104
 105 There are many tools you can use to translate this file. If you prefer
 106 to work on your client (and mainly if you expect to do a high volume
 107 of changes), we suggest you to use the `poedit` tool; we have also
 108 been accepted as a hosted project
 109 [hosted project in the Weblate online translation coordination service](https://weblate.org/projects/madewithcc). Weblate
 110 is completely based on free software tools, we invite you to get
 111 familiar with their interface.
 112
 113 ## Building the translated Markdown file
 114
 115 `po4a` provides a tool to integrate the translation back into a
 116 Markdown document, `po4a-translate`. I have only made first attempts
 117 with it, and we need to find ways to do several improvements. However,
 118 the following command will give you a good glimpse on how your
 119 finished translation looks:
 120
 121     po4a-translate -f text -m MadewithCreativeCommonsmostup-to-dateversion.md -p po/es/mwcc.po -l MadewithCreativeCommonsmostup-to-dateversion.es.md -l MadewithCreativeCommonsmostup-to-dateversion.es.md -L utf8 -M utf8 -k 20
 122
 123 What does it all mean?
 124
 125     -f text
 126
 127 The base format to/from which the translation is done is plain text.
 128
 129        -m MadewithCreativeCommonsmostup-to-dateversion.md
 130
 131 The name of your source document.
 132
 133        -p po/es/mwcc.po
 134
 135 Which translation to use. In this case, Spanish translation.
 136
 137        -l MadewithCreativeCommonsmostup-to-dateversion.es.md
 138
 139 Filename to use for the created translation. Do note that I'm
 140 specifying a name that implies Spanish.
 141
 142        -L utf8 -M utf8
 143
 144 Which character sets to use, both for the source and destination
 145 files.
 146
 147        -k 20
 148
 149 Minimum translation percentage for which to produce output. The
 150 default is 80% — To get a glimpse of your work in the early stages of
 151 a translation, use `-k` with a value smaller than the percentage you
 152 have achieved.