README_TRANSLATIONS

Last Revised: February 6, 2011

OVERVIEW

This directory contains all the text used by Mushroom Observer.
 
  de-DE.yml   German.
  el-GR.yml   Greek.
  en-US.yml   English.
  es-ES.yml   Spanish. (how_to_use page unfinished)
  pt-BR.yml   Brazillian Portuguese. (much unfinished)

(All are in UTF-8, the standard linux character encoding.)

To start translating the site into a new language, you can start with any of
these files.  See the guidelines and notes on syntax below for help.

--------------------------------------------------------------------------------

GUIDELINES

Please do not feel constrained by the original English.  If you can reword it
or otherwise express it better in your native language, please do so. 

We've tried to strike a compromise between formal and informal, sort of
symbolic of the role MushroomObserver plays between he professional and amateur
community. 

--------------------------------------------------------------------------------

SYNTAX

The basic structure of the files is simply a list of "keys" and "values": 

  key: value
  key: >
    Multiline values are terminated by a single blank line.

There are a few important things to watch:

1) Keys are fixed -- these are what the code uses to look up text for the site.

2) Square brackets and quotes can potentially confuse YAML.  When in doubt,
enclose your value with single or double-quotes:

  key: 'About: [name]'
  key: 'I said "hello".'
  key: "Click on 'Save'."

3) Most (but not all) values will be "Textilized", allowing you to include
formatting and links and such as you normally would when entering notes on the
site.  But note that internal links like _Agaricus_ will *not* work.

  key: This is __really__ cool!
  key: You can use "Textile":/observer/textile mark-up in these files.

4) Many translations allow on-the-fly substitutions.  We use [brackets] to hold
the place of an arbitrary string that will be inserted at run-time.  Do not change
the word(s) inside the square brackets!

  key: Editing Observation #[id]
  key: Please check our "todo list":[svn_repo]/trunk/TODO.
  key: Cancel (Show [object])
  key: Last Updated on [date] by [user].

5) We use a dorky convention to make it easy to see which values have not been
translated yet.  If the colon is followed by one space it has been translated,
if it is followed by more than one it has not.  I know it seems stupid, but this
is really important to help us keep things straight.

  key: translated
  key:  untranslated

6) There are a few special characters that aren't standard YAML syntax:

  <<hola>>      Double angle-brackets get translated into angle-quotes.
  \n\n          Force the extra blank line Textile requires between paragraphs.

7) Note that only the comments (lines starting with "#") at the very top of the
file will be kept; everything below is generated automatically from the English
template. 

--------------------------------------------------------------------------------

MAINTENANCE

All of the translations are updated using the English version as the template
using a rake task:

  rake lang:clean

The order of keys and the comments in the English file are preserved.  It
revises all the non-English translations to match the English file, fills in
missing keys, moves unrecognized keys to the bottom, and tells you how many are
missing in each file.  (Comments at the top of the non-English files are left
intact.)

Right now, the way to tell which keys were inserted from the English is to
search for colons followed by *two* spaces, instead of one.  If you decide to
follow this convention, remove the extra space from each entry you translate.
This way we can easily find the ones that still need to be translated. 

(**NOTE**: If you don't follow this two-space convention, "rake lang:clean"
could potentially clobber any translations which have two or more spaces.  It
will overwrite them with the updated English translation.  You have been
warned.) 

In the future we plan to insert comments before all the lines that need
translation, or for which the English has changed and might need updating.

--------------------------------------------------------------------------------

RUBY API

The core code is in vendors/plugins/globalite, but all access from MO goes
through a set of Symbol methods in helpers/symbol_extensions.rb:

   :app_title.l     Retrieves string unchanged.
   :app_title.t     Calls textilize_without_paragraph on it.
   :app_title.tp    Calls textilize on it.
   :app_title.tl    Same as .t but also processes internal links.
   :app_title.tpl   Same as .tp but also processes internal links.

These methods, of course, can be called from anywhere, not just views.  They
also all take an optional hash of arguments:

   :app_about_name.l(:name => 'Agaricus')

Use String.register_name(name) to initialize the look-up table for abbreviated
name links.  For example, "_A. campestris_" requires that it sees Agaricus
somewhere before.  Either you need to process a string with "_Agaricus_" in
it before doing "_A. campestris_", or you need to register Agaricus first.