Translating: Difference between revisions

From OLPC
Jump to navigation Jump to search
(→‎wiki pages: added section on how to maintain a translation)
(updated the fast & furious guide to the translating framework...)
Line 7: Line 7:
== fast & furious ==
== fast & furious ==


So you want to translate a wiki-page? Here's a summary:
So you want to translate a wiki-page? If the page has never been translated, please check [[#first translation]] below. Else here's a summary:

# create a <tt>/lang-xx</tt> sub-page for the translation (copy-pasting the original text as-is)
# using the (<tt>+/-</tt>) link in the ''blue-translations'' bar, edit the page's language navigation links by adding a link to your ''future'' page: <tt><nowiki>[[something/lang-xx|targetLanguage]]</nowiki></tt>. See [http://www.iana.org/assignments/language-subtag-registry IANA's lang codes].
#* eg: original page [[Core principles]] => [[Core principles/lang-es]] translated page
#* Keep in mind the guidelines for [[#editing /translations sub-page]].
# preserve section headers
# follow the <tt>/lang-xx</tt> ''missing'' link you've just created and paste the contents of the original page ''as-is'' (you should procure the original page's raw wiki-text).
#* add '''before''' each header a line with <tt>&lt;div id="''original header''"/&gt;</tt> (er... obviously, replacing <tt>''original header''</tt> by whatever '''is''' the original header... )
#* NOTE: in the blue-bar you will see to the right something like <tt>[ID# 30630]</tt> which the base version for your translation and should be used as the ''version'' parameter of <tt>[[Template:Translation|<nowiki>{{Translation | ...blah... }}</nowiki>]]</tt> you'll be adding.
#* this allows linking regardless of target language and/or its wording
#* it'll help you [[#maintaning the translation]].
# insert the <tt>[[Template:Translated Page|<nowiki>{{Translate Page | ...blah... }} template</nowiki>]]</tt> at the top
# paste the raw wiki-text into the new <tt><nowiki>[[something/lang-xx|targetLanguage]]</nowiki></tt> page
#* make sure you note the <tt>version ID</tt> of the original page and <tt>diff</tt> to the ''current'' version&mdash;as this will greatly simplify the updating to future editions of the original page!
# add <tt>[[Template:Ongoing Translation|<nowiki>{{Ongoing Translation}}</nowiki> template]]</tt> below it
## remove ''unwanted'' templates and or categories. In particular, replace the <tt>[[Template:Translations|<nowiki>{{Translations}}</nowiki>]]</tt>) with the <tt>[[Template:Translation|<nowiki>{{Translation | ...blah... }}</nowiki>]]</tt> at the top
##* make sure you note & update the ''version'' of the original page used&mdash;as this will greatly simplify [[#maintaning the translation]]!
# if the original page doesn't have it, insert the <tt>[[Template:Translations|<nowiki>{{Translations}}</nowiki> template]]</tt> at its top
## add <tt>[[Template:Ongoing Translation|<nowiki>{{Ongoing Translation}}</nowiki>]]</tt> below it
#* This is readily visible (and editable) by following the link present in the template when <tt>Show preview</tt> is used (a feature highly recommendable not only when translating)
## preserve section headers
# update the <tt>/translations</tt> page to link to your translation
##* add '''before''' each header a line with <tt>&lt;div id="''original header''"/&gt;</tt> (er... obviously, replacing <tt>''original header''</tt> by whatever '''is''' the original header... )
#* In our example, this would be the [[Core principles/translations]] page and will allow multi-lingual navigation of said page
##* this allows linking regardless of target language and/or its wording
Now you can go back to you the page, translate it at ease, and when you're finished, just remove the <tt>[[Template:Ongoing Translation|<nowiki>{{Ongoing Translation}}</nowiki> template]]</tt> tag.
Now you can go back to you the page, translate it at ease, and when you're finished, just remove the <tt>[[Template:Ongoing Translation|<nowiki>{{Ongoing Translation}}</nowiki>]]</tt> tag.

=== first translation ===

# you must ''edit'' the ''source / original'' page
## at the top, after any other header templates&mdash;like <tt><nowiki>{{OLPC}}</nowiki></tt>&mdash;insert <tt>[[Template:Translations|<nowiki>{{Translations}}</nowiki>]]</tt>
## save it (the source page)
# you will notice a ''missing'' link in the left of the blue bar that looks like <tt>something/translations</tt>, click on it to edit the language navigation section of the page
# in said <tt>something/translations</tt> page, make a link to the original version:
#* <tt><nowiki>[[something|originalLanguage]]</nowiki></tt> (ie: <nowiki>[[Core principles|english]]</nowiki>)
Follow the [[#editing /translations sub-page]] below on how to add ''your'' translation to it.

=== editing /translations sub-page ===

In the ''blue-translations'' bar there's a symbol (<tt>+/-</tt>) that lets you edit the available translations. The resulting page (which is extremely minimalist in that it basically just holds a single line with the links to the translated pages) should look like this in ''edit'':
<nowiki>[[Core principles|english]] | [[Core principles/lang-es|español]]</nowiki>
and the ''visual'':
<tt>{{:Core principles/translations}}</tt>
So to add a new translation, you would add <tt><nowiki>[[something/lang-xx|targetLanguage]]</nowiki></tt> replacing <tt>xx</tt> with the 2/3 letter code used to [http://www.iana.org/assignments/language-subtag-registry identify languages]. Please keep in mind the following:
# keep <tt>targetLanguage</tt> short and in its ''native'' form (ie: español, not spanish)
# there's a "'''&nbsp;|&nbsp;'''" (mark the spaces) between links,
# keep them in alphabetical order (as far as possible)


== wiki pages ==
== wiki pages ==
Line 57: Line 79:


In a wiki, an unlinked page is as good as no page; so we need to somehow make sure that people navigating the site actually can reach those pages in a sensible way. The current technique is based on three elements:
In a wiki, an unlinked page is as good as no page; so we need to somehow make sure that people navigating the site actually can reach those pages in a sensible way. The current technique is based on three elements:
# a template to be included in the [[Template:Translated Page|translated page]],
# a template to be included in the [[Template:Translation|translated page]],
# a template to be included in the [[Template:Translations|original page]], and
# a template to be included in the [[Template:Translations|original page]], and
# a sub-page indexing the original page's translations (<tt>originalPage/translations</tt>).
# a sub-page indexing the original page's translations (<tt>originalPage/translations</tt>).
Line 64: Line 86:
; translator : by keeping track of the <tt>original</tt> and <tt>diff</tt> (to ''current'') anybody can review if the current page is up-to-date in respect to the original.
; translator : by keeping track of the <tt>original</tt> and <tt>diff</tt> (to ''current'') anybody can review if the current page is up-to-date in respect to the original.


=== maintaing the translation ===
=== maintaning the translation ===


Wikis being what they are, mean that what you translated yesterday is not today's version... so how do you manage the ''evolution'' of the original? Fortunately, wiki pages have an essential thing: '''history'''; and an extremely useful function: '''diff'''. Remember when the <tt>[[Template:Translated Page|<nowiki>{{Translate Page | ...blah... }} template</nowiki>]]</tt> was added, there were two links embeded in it:
Wikis being what they are, mean that what you translated yesterday is not today's version... so how do you manage the ''evolution'' of the original? Fortunately, wiki pages have an essential thing: '''history'''; and an extremely useful function: '''diff'''. Remember when the <tt>[[Template:Translation|<nowiki>{{Translation | ...blah... }} template</nowiki>]]</tt> was added, there were two links embeded in it:
# version (ie: <tt>http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&oldid=30534</tt>)
# version (ie: <tt>http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&oldid=30534</tt>)
# diff (ie: <tt>http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&diff=current&oldid=30534</tt>)
# diff (ie: <tt>http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&diff=current&oldid=30534</tt>)

Revision as of 04:36, 4 April 2007

The very nature of the project is multi-lingual and multi-cultural. And although english is (currently) our lingua franca it may not be so in the future—or so we hope—as each community takes over the project and molds it to their needs and objectives.

In the meantime, here are some tips, tricks and things to keep in mind while trying to bridge the language barrier that will hopefully make everybody's life simpler and more productive.

NOTE: most of the things that follow are a personal PoV (by User:Xavi).

fast & furious

So you want to translate a wiki-page? If the page has never been translated, please check #first translation below. Else here's a summary:

  1. using the (+/-) link in the blue-translations bar, edit the page's language navigation links by adding a link to your future page: [[something/lang-xx|targetLanguage]]. See IANA's lang codes.
  2. follow the /lang-xx missing link you've just created and paste the contents of the original page as-is (you should procure the original page's raw wiki-text).
  3. paste the raw wiki-text into the new [[something/lang-xx|targetLanguage]] page
    1. remove unwanted templates and or categories. In particular, replace the {{Translations}}) with the {{Translation | ...blah... }} at the top
    2. add {{Ongoing Translation}} below it
    3. preserve section headers
      • add before each header a line with <div id="original header"/> (er... obviously, replacing original header by whatever is the original header... )
      • this allows linking regardless of target language and/or its wording

Now you can go back to you the page, translate it at ease, and when you're finished, just remove the {{Ongoing Translation}} tag.

first translation

  1. you must edit the source / original page
    1. at the top, after any other header templates—like {{OLPC}}—insert {{Translations}}
    2. save it (the source page)
  2. you will notice a missing link in the left of the blue bar that looks like something/translations, click on it to edit the language navigation section of the page
  3. in said something/translations page, make a link to the original version:
    • [[something|originalLanguage]] (ie: [[Core principles|english]])

Follow the #editing /translations sub-page below on how to add your translation to it.

editing /translations sub-page

In the blue-translations bar there's a symbol (+/-) that lets you edit the available translations. The resulting page (which is extremely minimalist in that it basically just holds a single line with the links to the translated pages) should look like this in edit:

[[Core principles|english]] | [[Core principles/lang-es|español]]

and the visual:

العربية| deutsch | Ελληνικά | english | español | français | 日本語 | 한국어 | português|русский

So to add a new translation, you would add [[something/lang-xx|targetLanguage]] replacing xx with the 2/3 letter code used to identify languages. Please keep in mind the following:

  1. keep targetLanguage short and in its native form (ie: español, not spanish)
  2. there's a " | " (mark the spaces) between links,
  3. keep them in alphabetical order (as far as possible)

wiki pages

You are not forced by any means to use what follows—although it may save some time and help develop a standard way of doing things. By no means we are implying this is the best way, and some steps may seem arbitrary, and not really optimal; although their cost may be worthwhile. Any feedback is welcome!

The 'basic' structure of a 'standard' translation is based on the following premises:

  1. there's a base page you want in another language
  2. you want to keep it as a 'mirror' translation
  3. little or no reverse-flow towards the original

One of the main problems when translating is that your personal choice may not be the best one. Text-wise that is not a problem, and here the wiki spirit shows the true power by allowing a more democratic choice of wording. The problem arises from the fact that we are not translating text but also structure (headers, sections, etc.). So if we happen to pick a 'wrong' section header, anything linking to it will be broken when we try to make things better—defeating the wiki kaizen spirit of constant improvements. In order to avoid getting stuck in bad translations, here are some techniques and tips that may help the kaizen spiriti of a wiki-editor.

creating the translated page

Usually you can give a page any name you like, although I recommend using a sub-page technique that uses the language identification: originalPage/lang-xx. This comes in handy as the volume of pages in the xx language grows and won't be able to recall all the exact names of all the translations. So if you find yourself translating a link to say The OLPC Wiki you may wonder what is the exact translation used for your language. Appending /lang-xx to the link takes care of that. If by any chance the page hasn't been translated yet, you may create a redirect page to the original version and do the translation later.

how to set up the translated page

A page worth translating will surely be split up in sections and sub-sections, which are latter used as anchors by the hyper-text system, allowing to refer and link to specific sections. Again, if we translate the section/anchor name, when a better translation is found the links will brake. A simple solution (leveraging on the /lang-xx technique) is to avoid the problem altogether by preserving the original anchors.

For example, if we were to translate the section ==Home==, we could translate it into spanish as either Hogar or Casa—context will probably make one more likely than the other, but you can't always be certain. The problem arises when that header is being used as an anchor for some link: OLPC Human Interface Guidelines/The Laptop Experience/Zoom Metaphor#Home. This 'example' link, is very interesting (although extremely peculiar and rare) because it depends on the original title page OLPC Human Interface Guidelines, the chained subpages The Laptop Experience and Zoom Metaphor, and finally the anchor/section name Home. Each one of them may have multiple possible translations.

The simplest solution is to make the links independent of the translation. The /lang-xx takes care of the page-links and the following trick of the anchor:

 # ORIGINAL          # TRANSLATION 1      # TRANSLATION REVIEWED
                     <div id="Home"/>     <div id="Home"/>
 == Home ==          == Casa ==           == Hogar ==

While the links will always remain basically the same:

OLPC Human Interface Guidelines/The Laptop Experience/Zoom Metaphor#Home
OLPC Human Interface Guidelines/The Laptop Experience/Zoom Metaphor/lang-es#Home

NOTE: only the /lang-xx has been added—greatly simplifying the linking.

hooking the translation to the wiki

In a wiki, an unlinked page is as good as no page; so we need to somehow make sure that people navigating the site actually can reach those pages in a sensible way. The current technique is based on three elements:

  1. a template to be included in the translated page,
  2. a template to be included in the original page, and
  3. a sub-page indexing the original page's translations (originalPage/translations).

This triad serves two main uses: reader & translator.

reader
it allows the multi-lingual navigation by presenting all the translations of a given page in a homogeneous way while avoiding the typical error of forgetting to update all translations with the 'new' translation.
translator
by keeping track of the original and diff (to current) anybody can review if the current page is up-to-date in respect to the original.

maintaning the translation

Wikis being what they are, mean that what you translated yesterday is not today's version... so how do you manage the evolution of the original? Fortunately, wiki pages have an essential thing: history; and an extremely useful function: diff. Remember when the {{Translation | ...blah... }} template was added, there were two links embeded in it:

  1. version (ie: http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&oldid=30534)
  2. diff (ie: http://wiki.laptop.org/index.php?title=The_OLPC_Wiki&diff=current&oldid=30534)

The actual http-link can be extracted initially from the translated page's history page.

The version number 30534 now appears in the original page in the upper right corner. Please note that the diff should compare the current (it's a keyword, not a number) with the translated version ID#.

So at any time, you can verify the changes (if any) of the translated source-version-# with the current-version-#—just by following the link.

IMPORTANT: When updating a translation, you must update the version-# of the links. (Just copy paste the # shown in the original page). This will allow future translators or reviewers to work only in the sections that have changed without actually having to review both documents in order to find differences (some of which may be trivial from the text perspective, but crucial from the exactitude and validity of the content—ie:latest build, etc).

laptop.org

Please refer to the Localization page for further information on the l10n efforts of www.laptop.org.

foreign wiki pages

As the global effort picks up speed, it's our hope and interest that local communities will develop things in their local languages that we may want to share globally. This is already happening, and we are trying to develop the necessary templates to make life simpler (probably a variation on the local translation templates mentioned above). In the meantime, take a look at Hello World!.