Commit f6a3a641 authored by Pat David's avatar Pat David
Browse files

Added page detailing how to create a translation

parent b8e68d6d
......@@ -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:
......
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.
......
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.
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>
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.
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment