[gimp-web/gimp-web-static] Added page detailing how to create a translation

From: Pat David <patdavid src gnome org>
To: commits-list gnome org
Cc:
Subject: [gimp-web/gimp-web-static] Added page detailing how to create a translation
Date: Thu, 27 Aug 2015 17:12:42 +0000 (UTC)
commit f6a3a641d239e00500503925c52fef7558823bf7
Author: Pat David <patdavid gmail com>
Date:   Thu Aug 27 12:12:28 2015 -0500

    Added page detailing how to create a translation

 content/about/meta/index.fr.md        |    5 +-
 content/about/meta/index.md           |    7 +-
 content/about/meta/translating.fr.md  |   81 ++---------------
 content/about/meta/translating.md     |  161 +++++++++++++++++----------------
 content/about/meta/translations.fr.md |   78 ++++++++++++++++
 content/about/meta/translations.md    |  119 ++++++++++++++++++++++++
 6 files changed, 293 insertions(+), 158 deletions(-)
---
diff --git a/content/about/meta/index.fr.md b/content/about/meta/index.fr.md
index 5ef61b3..a3cbbea 100644
--- a/content/about/meta/index.fr.md
+++ b/content/about/meta/index.fr.md
@@ -11,11 +11,12 @@ I (Pat David) am creating this page to keep notes and information for building/m
 
 (Meta) pages of interest:
 
+* [Editing the Front Page](./frontpage.html)
+* [Creating a Translation](./translating.html)
 * [To Do](./to-do/)
 * [Using Pelican](./using-pelican/)
 * [Markdown Cheatsheet](./markdown.html)
-* [Edit the Front Page]({filename}./frontpage.md)
-* [Translations]({filename}./translating.fr.md) 
+* [Translations (more info)](./translations.html)
 
 
 Le travail que je fais ici est basée sur un couple de suggestions de la dernière année (ou plus, je suis 
sûr) pour actualiser la conception de WGO. En particulier, je l'avais créé une brève maquette pour montrer et 
ai été d'utiliser cela comme une sorte de guide visuel pour approcher la page principale. Vous pouvez voir 
que maquette .PNG ici (~ 1.8MB), ou un petit aperçu:
diff --git a/content/about/meta/index.md b/content/about/meta/index.md
index 6a89445..0fb857b 100644
--- a/content/about/meta/index.md
+++ b/content/about/meta/index.md
@@ -1,6 +1,6 @@
 Title: Meta 
 Date: 2015-07-29T14:40:35-05:00
-Modified: 2015-08-10T14:53:46-05:00
+Modified: 2015-08-27T12:06:35-05:00
 Author: Pat David
 Summary: A page about the new site.
 lang: en
@@ -10,11 +10,12 @@ I (Pat David) am creating this page to keep notes and information for building/m
 
 (Meta) pages of interest:
 
-* [Editing the Front Page]({filename}./frontpage.md)
+* [Editing the Front Page](./frontpage.html)
+* [Creating a Translation](./translating.html)
 * [To Do](./to-do/)
 * [Using Pelican](./using-pelican/)
 * [Markdown Cheatsheet](./markdown.html)
-* [Translations]({filename}./translating.md)
+* [Translations (more info)](./translations.html)
 
 
 The work I am doing here is based on a couple of suggestions over the past year (or more, I'm sure) to 
refresh the design of WGO.
diff --git a/content/about/meta/translating.fr.md b/content/about/meta/translating.fr.md
index b575b3d..1761607 100644
--- a/content/about/meta/translating.fr.md
+++ b/content/about/meta/translating.fr.md
@@ -1,77 +1,10 @@
-Title: Translations (i18n)
-Date: 2015-08-21T11:45:47-05:00
+Title: Créer Traductions
+Date: 2015-08-27T10:18:03-05:00
 Author: Pat David
-lang: fr 
+lang: fr
+slug: creating-translations
 
-Pelican avait déjà une belle simple support pour la traduction des pages et des articles.
+This is the French version of the "Creating Translations" page.
 
-Pour faire une traduction, il suffit de créer un autre fichier avec le fichier de base. Tant que le *slug* 
serait le même, un fichier serait considérée comme une traduction de l'autre. Définition de l'attribut `lang` 
dans les métadonnées du fichier signalerait ce type de fichier, il est.
-<small>
-La limace est actuellement généré à partir du titre de la page dans les métadonnées.
-</small>
-
-A titre d'exemple, ce fichier est:
-
-    content/about/meta/translating.md
-
-Et les métadonnées au sommet de ce fichier ressemble à ceci:
-
-    Title: Translations (i18n)
-    Date: 2015-08-21T11:45:47-05:00
-    Author: Pat David
-    lang: en
-
-Pour créer une version traduite de cette page, nous aimerions créer un nouveau fichier:
-
-    content/about/meta/translating.fr.md
-
-Les métadonnées serait un peu différente, en ce que l'attribut `lang` serait différent maintenant:
-
-
-    Title: Translations (i18n)
-    Date: 2015-08-21T11:45:47-05:00
-    Author: Pat David
-    lang: fr
-
-Sinon tout le reste pourrait rester le même.
-
-En faisant cela, Pelican va maintenant automatiquement la liste de la traduction (s) étant disponible (par 
défaut il est répertorié juste sous le titre). Il serait généralement ressembler à ceci (pour une traduction 
française étant disponibles):
-
-    Translations: fr
-
-
-## i18n_subsites
-
-Avec la mise en œuvre de i18n_subsites, le comportement est essentiellement le même.
-
-La différence est maintenant que d'un sous-site entièrement nouveau est construit. Le site avec les 
anciennes traductions servirait une page traduite, mais ce serait une page statique simple.
-
-Cela signifie que tous les liens hors de la page à d'autres contenus souhaitez-vous apporter à la langue par 
défaut (en) à nouveau. Si cette page avait une traduction, et que vous vouliez le voir, vous devez cliquer 
sur l'option de traduction appropriée nouveau.
-
-L'option de traduction d'une seule page ne dispose d'aucun mécanisme pour traduire les modèles aussi bien 
(juste le contenu de la page).
-
-Mise en œuvre du plugin i18n_subsites permet désormais un sous-ensemble du site qui sera construit sur la 
base de l'option de langue. Donc, en cliquant sur une traduction de langue pour une page va maintenant mettre 
l'utilisateur au sous-site correspondant.
-
-Ce sont les sous-sites qui se créés par exemple:
-
-    gimp.org/fr/about/...
-    gimp.org/de/about/...
-
-Et ainsi de suite pour chaque traduction.
-
-
-### Fallback
-
-Une fonctionnalité intéressante du plugin i18n_subsites est que les pages qui sont liées, mais le manque 
d'une traduction, seront toujours montrer la version **en** comme solution de repli.
-
-
-* [A link to meta](/about/meta/) `[A link to meta](/about/meta/)`  
-    Leads back to english version of the site from everywhere.
-* [<del>A link to meta</del>](./about/meta/) `[A link to meta](./about/meta/)`  
-    Doesn't work right (as expected).
-* [A link to meta](../../about/meta/) `[A link to meta](../../about/meta/)`  
-    Leads to the translated version of the page correctly!
-* [A link to meta](../meta/) `[A link to meta](../meta/)`  
-    Also leads back to translated version of the page correctly.
-* [A link to meta](./) `[A link to meta](./)`  
-    Also leads back to translated version of the page correctly.
+I'm sorry it's not in French just yet.
+It's really just here to serve as an example of a translated page.
diff --git a/content/about/meta/translating.md b/content/about/meta/translating.md
index 2a1cadb..50ce246 100644
--- a/content/about/meta/translating.md
+++ b/content/about/meta/translating.md
@@ -1,118 +1,121 @@
-Title: Translations (i18n)
-Date: 2015-08-21T11:45:47-05:00
+Title: Creating Translations
+Date: 2015-08-27T10:18:03-05:00
 Author: Pat David
 lang: en
+slug: creating-translations
 
-Pelican already had a nice simple support for translating pages and articles.
+I am assuming you are reading this because you'd like to submit a translation of an article?
 
-To do a translation, simply create another file alongside the base file.
-As long as the *slug* would be the same, one file would be considered a translation of the other.
-Setting the `lang` attribute in the file metadata would signal what type of file it is.
+If so - YAY!
+**Thank you** for contributing!
 
-<small>
-The *slug* is currently generated from the page title in the metadata.
-</small>
+Creating a new translation of an existing article is fairly straightforward:
 
-As an example, this file is:
+1. Find the source file to translate.
+2. Create a new file in the same place, with the lang in the filename:  
+    original: `translating.md`  
+    translation: `translating.fr.md`
 
-    content/about/meta/translating.md
+3. Add the `lang` metadata to both the original and translation file:  
+    add `lang: en` to original  
+    add `lang: fr` to translation (example for French)
 
-And the metadata at the top of this file looks like this:
+4. To have different titles (translated title as well):
+    * Add the same `slug` metadata to both files:  
+        add `slug: unique-slug-name` to both original and translation file
+    * Then each file can have different titles.
 
-    Title: Translations (i18n)
-    Date: 2015-08-21T11:45:47-05:00
-    Author: Pat David
-    lang: en
-
-To create a translated version of this page, we would create a new file:
-
-    content/about/meta/translating.fr.md
-
-The metadata would look slightly different, in that the `lang` attribute would be different now:
-
-
-    Title: Translations (i18n)
-    Date: 2015-08-21T11:45:47-05:00
-    Author: Pat David
-    lang: fr
-
-Otherwise everything else could stay the same.
-
-When doing this, Pelican will now automatically list the translation(s) being available
-(by default it is listed just under the title).
-It would typically look like this (for a French translation being available):
+## Locate the Article You'll Translate
 
-    Translations: fr
+Find the article source you want to translate.
+I will use this article you're reading as an example.
+It can be found in the source at this location:
 
+    /content/about/meta/translating.md
 
-## i18n_subsites
+Now create a new file in the same location, with a slightly different filename to indicate the new language.
+A handy convention to follow is to use the ISO 639-1 two-letter code for the new language in the filename.
+So to include a French version of this page, we will create a new file:
 
-With the implementation of i18n_subsites, the behavior is mostly the same.
+    /content/about/meta/translating.fr.md
 
-The difference now is that an entirely new sub-site is built.
-The site with the old translations would serve a translated page, but it would be a simple static page.
 
-This means that any links off the page to other content would bring you to the default language (en) again.
-*If* that page had a translation, and you wanted to see it, you would have to click on the appropriate 
translation option again.
+## Modify/Add to Metadata
 
-The single-page translation option doesn't have any mechanism for translating the templates as well (just 
the page content).
+### lang attribute
 
-Implementation of the i18n_subsites plugin now allows an entire sub-site to be built based on the language 
option.
-So clicking on a language translation for a page will now bring the user to the corresponding sub-site.
+The metadata for this article looks like this (Markdown):
 
-These are the sub-sites that get created for example:
+    Title: Creating Translations
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
 
-    gimp.org/fr/about/...
-    gimp.org/de/about/...
+There needs to be an addition of a `lang` attribute to **both** the original and new translation of the 
article.
+So this (english) version of the file must now get a `lang` attribute that identifies it as such:
 
-And so on for each translation.
+**translating.md:**
 
+    :::markdown hl_lines="4 4"
+    Title: Creating Translations
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
+    lang: en
 
-### Fallback
+Similarly, the new translation file must also get a `lang` attribute for the new language:
 
-A nice feature of the i18n_subsites plugin is that pages that are linked, but lack a translation, will still 
show the **en** version as a fallback.
+**translating.fr.md**
 
+    :::markdown hl_lines="4 4"
+    Title: Creating Translations
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
+    lang: fr
 
-### I Can't Believe That Worked...
 
-So I had to hack at the `mimic_hierarchy` plugin again to fix one piece of small weirdness with 
i18n_subsites.
+### slug attribute & different title
 
-The problem was that if you had a file, and it's translation:
+If you want to use a translated version of the article title, it will require one extra piece of metadata to 
work properly.
+(Hopefully temporarily - still working on this).
 
-    /about/meta/index.md
-    /about/meta/index.fr.md
+The addition of the `slug` attribute will let a different title be used in the translated version of the 
article.
+The actual value of the attribute is left to the author to choose, but it *needs to match* in all the 
translations of a page.
 
-Then the path/files that get created with i18n look like this, respectively:
+So the base english article will need this `slug` attribute added:
 
-    gimp.org/about/meta/index.html
-    gimp.org/fr/about/meta/index.fr.html
+**translating.md:**
 
-Which is _less_ than ideal.  The reason is that if I wanted to get to the first instance with a pretty url, 
I could go to:
+    :::markdown hl_lines="5"
+    Title: Creating Translations
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
+    lang: en
+    slug: creating-translations
 
-    gimp.org/about/meta/
+Any other translation will need *the exact same* slug added as well:
 
-Likewise, linking to that page internally could be done easily through either `{filename}` to the 
pre-rendered file:
+**translating.fr.md**
 
-    [A link to meta]({filename}../../about/meta/index.md)
+    :::markdown hl_lines="5"
+    Title: Creating Translations
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
+    lang: fr
+    slug: creating-translations
 
-Which would render this: [A link to meta]({filename}../../about/meta/index.md)
+Once that is done, the `Title` attribute can be different between the two files and they will still be 
marked as translations of each other:
 
-The problem with using this link is that if it is called from a translated page, it will cause it to lead 
back to the **en** version of the page.
-A better solution would be to allow internal links to simply point to locations directly without having to 
worry about the sub-site.
-Some different link types to test:
+**translating.fr.md**
 
-* [A link to meta](/about/meta/) `[A link to meta](/about/meta/)`  
-    Leads back to english version of the site from everywhere.
-* [<del>A link to meta</del>](./about/meta/) `[A link to meta](./about/meta/)`  
-    Doesn't work right (as expected).
-* [A link to meta](../../about/meta/) `[A link to meta](../../about/meta/)`  
-    Leads to the translated version of the page correctly!
-* [A link to meta](../meta/) `[A link to meta](../meta/)`  
-    Also leads back to translated version of the page correctly.
-* [A link to meta](./) `[A link to meta](./)`  
-    Also leads back to translated version of the page correctly.
+    :::markdown hl_lines="1"
+    Title: Créer Traductions
+    Date: 2015-08-27T10:18:03-05:00
+    Author: Pat David
+    lang: fr
+    slug: creating-translations
 
-At the moment, we basically need to use relative links to the output files, which will then work no matter 
what the translation is it's used from.
 
-The other option is to continue using direct linking to files pre-rendering, as in the Pelican manual (and 
above).
-The writer just needs to be careful to link to the correct place when doing this.
+<style>
+.codehilite .err {
+    border: none;
+}
+</style>
diff --git a/content/about/meta/translations.fr.md b/content/about/meta/translations.fr.md
new file mode 100644
index 0000000..0cca675
--- /dev/null
+++ b/content/about/meta/translations.fr.md
@@ -0,0 +1,78 @@
+Title: Traductions (i18n)
+Date: 2015-08-21T11:45:47-05:00
+Author: Pat David
+lang: fr 
+slug: translations
+
+Pelican avait déjà une belle simple support pour la traduction des pages et des articles.
+
+Pour faire une traduction, il suffit de créer un autre fichier avec le fichier de base. Tant que le *slug* 
serait le même, un fichier serait considérée comme une traduction de l'autre. Définition de l'attribut `lang` 
dans les métadonnées du fichier signalerait ce type de fichier, il est.
+<small>
+La limace est actuellement généré à partir du titre de la page dans les métadonnées.
+</small>
+
+A titre d'exemple, ce fichier est:
+
+    content/about/meta/translating.md
+
+Et les métadonnées au sommet de ce fichier ressemble à ceci:
+
+    Title: Translations (i18n)
+    Date: 2015-08-21T11:45:47-05:00
+    Author: Pat David
+    lang: en
+
+Pour créer une version traduite de cette page, nous aimerions créer un nouveau fichier:
+
+    content/about/meta/translating.fr.md
+
+Les métadonnées serait un peu différente, en ce que l'attribut `lang` serait différent maintenant:
+
+
+    Title: Translations (i18n)
+    Date: 2015-08-21T11:45:47-05:00
+    Author: Pat David
+    lang: fr
+
+Sinon tout le reste pourrait rester le même.
+
+En faisant cela, Pelican va maintenant automatiquement la liste de la traduction (s) étant disponible (par 
défaut il est répertorié juste sous le titre). Il serait généralement ressembler à ceci (pour une traduction 
française étant disponibles):
+
+    Translations: fr
+
+
+## i18n_subsites
+
+Avec la mise en œuvre de i18n_subsites, le comportement est essentiellement le même.
+
+La différence est maintenant que d'un sous-site entièrement nouveau est construit. Le site avec les 
anciennes traductions servirait une page traduite, mais ce serait une page statique simple.
+
+Cela signifie que tous les liens hors de la page à d'autres contenus souhaitez-vous apporter à la langue par 
défaut (en) à nouveau. Si cette page avait une traduction, et que vous vouliez le voir, vous devez cliquer 
sur l'option de traduction appropriée nouveau.
+
+L'option de traduction d'une seule page ne dispose d'aucun mécanisme pour traduire les modèles aussi bien 
(juste le contenu de la page).
+
+Mise en œuvre du plugin i18n_subsites permet désormais un sous-ensemble du site qui sera construit sur la 
base de l'option de langue. Donc, en cliquant sur une traduction de langue pour une page va maintenant mettre 
l'utilisateur au sous-site correspondant.
+
+Ce sont les sous-sites qui se créés par exemple:
+
+    gimp.org/fr/about/...
+    gimp.org/de/about/...
+
+Et ainsi de suite pour chaque traduction.
+
+
+### Fallback
+
+Une fonctionnalité intéressante du plugin i18n_subsites est que les pages qui sont liées, mais le manque 
d'une traduction, seront toujours montrer la version **en** comme solution de repli.
+
+
+* [A link to meta](/about/meta/) `[A link to meta](/about/meta/)`  
+    Leads back to english version of the site from everywhere.
+* [<del>A link to meta</del>](./about/meta/) `[A link to meta](./about/meta/)`  
+    Doesn't work right (as expected).
+* [A link to meta](../../about/meta/) `[A link to meta](../../about/meta/)`  
+    Leads to the translated version of the page correctly!
+* [A link to meta](../meta/) `[A link to meta](../meta/)`  
+    Also leads back to translated version of the page correctly.
+* [A link to meta](./) `[A link to meta](./)`  
+    Also leads back to translated version of the page correctly.
diff --git a/content/about/meta/translations.md b/content/about/meta/translations.md
new file mode 100644
index 0000000..d7ef93d
--- /dev/null
+++ b/content/about/meta/translations.md
@@ -0,0 +1,119 @@
+Title: Translations (i18n)
+Date: 2015-08-21T11:45:47-05:00
+Author: Pat David
+lang: en
+slug: translations
+
+Pelican already had a nice simple support for translating pages and articles.
+
+To do a translation, simply create another file alongside the base file.
+As long as the *slug* would be the same, one file would be considered a translation of the other.
+Setting the `lang` attribute in the file metadata would signal what type of file it is.
+
+<small>
+The *slug* is currently generated from the filename.
+</small>
+
+As an example, this file is:
+
+    content/about/meta/translating.md
+
+And the metadata at the top of this file looks like this:
+
+    Title: Translations (i18n)
+    Date: 2015-08-21T11:45:47-05:00
+    Author: Pat David
+    lang: en
+
+To create a translated version of this page, we would create a new file:
+
+    content/about/meta/translating.fr.md
+
+The metadata would look slightly different, in that the `lang` attribute would be different now:
+
+
+    Title: Translations (i18n)
+    Date: 2015-08-21T11:45:47-05:00
+    Author: Pat David
+    lang: fr
+
+Otherwise everything else could stay the same.
+
+When doing this, Pelican will now automatically list the translation(s) being available
+(by default it is listed just under the title).
+It would typically look like this (for a French translation being available):
+
+    Translations: fr
+
+
+## i18n_subsites
+
+With the implementation of i18n_subsites, the behavior is mostly the same.
+
+The difference now is that an entirely new sub-site is built.
+The site with the old translations would serve a translated page, but it would be a simple static page.
+
+This means that any links off the page to other content would bring you to the default language (en) again.
+*If* that page had a translation, and you wanted to see it, you would have to click on the appropriate 
translation option again.
+
+The single-page translation option doesn't have any mechanism for translating the templates as well (just 
the page content).
+
+Implementation of the i18n_subsites plugin now allows an entire sub-site to be built based on the language 
option.
+So clicking on a language translation for a page will now bring the user to the corresponding sub-site.
+
+These are the sub-sites that get created for example:
+
+    gimp.org/fr/about/...
+    gimp.org/de/about/...
+
+And so on for each translation.
+
+
+### Fallback
+
+A nice feature of the i18n_subsites plugin is that pages that are linked, but lack a translation, will still 
show the **en** version as a fallback.
+
+
+### I Can't Believe That Worked...
+
+So I had to hack at the `mimic_hierarchy` plugin again to fix one piece of small weirdness with 
i18n_subsites.
+
+The problem was that if you had a file, and it's translation:
+
+    /about/meta/index.md
+    /about/meta/index.fr.md
+
+Then the path/files that get created with i18n look like this, respectively:
+
+    gimp.org/about/meta/index.html
+    gimp.org/fr/about/meta/index.fr.html
+
+Which is _less_ than ideal.  The reason is that if I wanted to get to the first instance with a pretty url, 
I could go to:
+
+    gimp.org/about/meta/
+
+Likewise, linking to that page internally could be done easily through either `{filename}` to the 
pre-rendered file:
+
+    [A link to meta]({filename}../../about/meta/index.md)
+
+Which would render this: [A link to meta]({filename}../../about/meta/index.md)
+
+The problem with using this link is that if it is called from a translated page, it will cause it to lead 
back to the **en** version of the page.
+A better solution would be to allow internal links to simply point to locations directly without having to 
worry about the sub-site.
+Some different link types to test:
+
+* [A link to meta](/about/meta/) `[A link to meta](/about/meta/)`  
+    Leads back to english version of the site from everywhere.
+* [<del>A link to meta</del>](./about/meta/) `[A link to meta](./about/meta/)`  
+    Doesn't work right (as expected).
+* [A link to meta](../../about/meta/) `[A link to meta](../../about/meta/)`  
+    Leads to the translated version of the page correctly!
+* [A link to meta](../meta/) `[A link to meta](../meta/)`  
+    Also leads back to translated version of the page correctly.
+* [A link to meta](./) `[A link to meta](./)`  
+    Also leads back to translated version of the page correctly.
+
+At the moment, we basically need to use relative links to the output files, which will then work no matter 
what the translation is it's used from.
+
+The other option is to continue using direct linking to files pre-rendering, as in the Pelican manual (and 
above).
+The writer just needs to be careful to link to the correct place when doing this.
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]