Translating/HIG

From OLPC
< Translating
Revision as of 05:51, 26 September 2007 by Xavi (talk | contribs) (Reverted edits by 63.241.9.240 (Talk); changed back to last version by Xavi)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

So you want to put the OLPC Human Interface Guidelines in your language? Don't be intimidated by all the mumbo-jumbo of the internals, admittedly not the most user friendly, but once you get the hang of it you'll be able to concentrate in the content and not the structure—but you must still keep an eye on it! ;)

Soon an explanation on how to hook things up, and not die in the process...

native structure

The original or native structure of the HIG is a set of sub-pages and sub-sub-pages (iirc 4 levels):

OLPC Human Interface Guidelines
       OLPC Human Interface Guidelines/Activities
              OLPC Human Interface Guidelines/Activities/Activity Basics
              ...
       OLPC Human Interface Guidelines/Design Fundamentals
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience
              ...
       ...

The original structure has a set of navigational templates that link these pages and its navigation. IIRC, there are 4 templates handling this.

native navigation structure

This section is a stub. You can help the wiki by expanding it.

The HIG uses a series of templates specific to navigate it.

translated structure

Basically we add sub-pages denoting the translated version onto the structure:

OLPC Human Interface Guidelines/lang-es
       OLPC Human Interface Guidelines/Activities/lang-es
              OLPC Human Interface Guidelines/Activities/Activity Basics/lang-es
              ...
       OLPC Human Interface Guidelines/Design Fundamentals/lang-es
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/lang-es
              ...
       ...

And use a modified version of the navigational templates. Same name with a -lang postifx, and some reworking in the parameters (mainly adding the language code).

Because we want people to be able to find the translated versions, as with the multi-lingual /translations page, we now have those kind of pages here too:

OLPC Human Interface Guidelines/translations
       OLPC Human Interface Guidelines/Activities/translations
              OLPC Human Interface Guidelines/Activities/Activity Basics/translations
              ...
       OLPC Human Interface Guidelines/Design Fundamentals/translations
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/translations
              ...
       ...

So once you add a translated page, you should also add it to the /translations page of the original.

The most hideous (or ugly) aspect is that you want to preserve links regardless of the language, and also we must take into consideration that the term originally used by the translator may not be the best-fit for the community as a whole. So, how do we get around the real possibility that when translating Home, you may have used a term that although valid, is not really the best one and that we want to modify it without breaking things up? Two things:

  1. preserve the original section headers (using the {{anchor|originalSectionHeader}} trick)
  2. factor out the page title into a specific page:

OLPC Human Interface Guidelines/lang-es                    # this is an exception - no title for the root
       OLPC Human Interface Guidelines/Activities/lang-es/title
              OLPC Human Interface Guidelines/Activities/Activity Basics/lang-es/title
              ...
       OLPC Human Interface Guidelines/Design Fundamentals/lang-es/title
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/lang-es/title
              ...
       ...

NOTE: the /title page is a sub-page of your /lang-xx page! Be careful not to translate / step-over some other language!

native navigation structure

This section is a stub. You can help the wiki by expanding it.

We have basically added a new parameter to the native templates in order to deal with the /lang-xx issues.

The language extended navigation templates use these title subpages to present things the way the look. The down side to this is that you want to preserve said 'titles' within the document, forcing you to do some very weird looking code:

[[OLPC Human Interface Guidelines/Core Ideas/lang-es|{{:OLPC Human Interface Guidelines/Core Ideas/lang-es/title}}]]
displays as: Ideas Centrales
being the linked page OLPC Human Interface Guidelines/Core Ideas/lang-es,
and the displayed text Ideas Centrales 

whose sole purpose is to link a page showing the translated title...

Summarizing, when translating the HIG, you should end up with the following structure:

OLPC Human Interface Guidelines
OLPC Human Interface Guidelines/translations
OLPC Human Interface Guidelines/lang-es
OLPC Human Interface Guidelines/lang-es/title                    # this is an exception - no title for the root
       OLPC Human Interface Guidelines/Activities
       OLPC Human Interface Guidelines/Activities/translations
       OLPC Human Interface Guidelines/Activities/lang-es
       OLPC Human Interface Guidelines/Activities/lang-es/title
              OLPC Human Interface Guidelines/Activities/Activity Basics
              OLPC Human Interface Guidelines/Activities/Activity Basics/translations
              OLPC Human Interface Guidelines/Activities/Activity Basics/lang-es
              OLPC Human Interface Guidelines/Activities/Activity Basics/lang-es/title
              ...
       OLPC Human Interface Guidelines/Design Fundamentals
       OLPC Human Interface Guidelines/Design Fundamentals/translations
       OLPC Human Interface Guidelines/Design Fundamentals/lang-es
       OLPC Human Interface Guidelines/Design Fundamentals/lang-es/title
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/translations
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/lang-es
              OLPC Human Interface Guidelines/Design Fundamentals/Know Your Audience/lang-es/title

NOTE: in italics are the pages that already exist, and shouldn't be created, just modified. And in the example, the spanish version (/lang-es) are used but you should create the whatever /lang-xx for you language using the standard code (see above for the link).