[squirrelmail.git] / doc / translating_help.txt

Translating the help files.
===========================

I have tried to write the help files in plain english with good grammer.
Since English is not my strong point you probably can't tell, but I hope it 
helps.

The help files, at this point, are divided into functional areas.  Each .hlp 
file represents a different functional block of how the program looks to the 
user.

Hopefully as SquirrelMail gets more widely used, non-english translations will
be used to make other non-english translations.  You might want to keep this
in mind when writing yours.  Remember that these will be used all over the
world and in many different environments so local language dialects might 
confuse someone else. 

File Structure
==============

All translated files should be placed under the help directory.  Under the
help directory create another directory. This directory MUST be named in the
two letter standard abbreviation for the language. English is "en" and Polish 
would be "pl" for example.

The help files are written in a basic xml format.  Don't worry, XML isn't hard
at all.  All it does is contain values inside tags like <start> and </start>.
For these help files, the tags must be on their own line like this:
   <tag>
      Value for this tag
   </tag>

There are two types of main tags: <chapter> and <section>.  There can be only 
one <chapter> tag in a .hlp file.  However, there can be many <section> tags.
Inside each of these tags, there can be any combination of any of the following
tags:  <title>, <description>, <summary>.  Here is an example:

                     | <chapter>
 The title can only  |    <title>
 be one line long    |       My first chapter   
                     |    </title>
 Summary may be many |    <summary>
 lines, but is short |       Just a brief summary
                     |    </summary>
                     |    <description>
 Description can be  |       This is a more detailed description that
 very long.  It is   |       can span many lines.  Usually this is the 
 the main part of    |       bulk of the help section or chapter description.
 the help section.   |    </description>
                     | </chapter>


Translating
===========

To translate, just copy all the .hlp files from help/en into the new directory
that you created for this language (i.e.  help/pl).  You only need to translate
what is between the tags.  Do not translate the actual tags such as <chapter> 
or <summary>.  The tag names need to remain in English.  You should only translate
the text between tags.

Often there may be other HTML tags such as <b> for bold or <a href...> to make
a link.  If you see any of these tags, just leave them and don't translate
them either.  Only what is contained inside them if needed.

That should be all!!
Commit	Line	Data
36c24f4f	1	Translating the help files.
390372b4	2	===========================
36c24f4f	3
36c24f4f	4	I have tried to write the help files in plain english with good grammer.
390372b4	5	Since English is not my strong point you probably can't tell, but I hope it
390372b4	6	helps.
36c24f4f	7
1e63b430	8	The help files, at this point, are divided into functional areas. Each .hlp
efb05555	9	file represents a different functional block of how the program looks to the
efb05555	10	user.
36c24f4f	11
1e63b430	12	Hopefully as SquirrelMail gets more widely used, non-english translations will
efb05555	13	be used to make other non-english translations. You might want to keep this
	14	in mind when writing yours. Remember that these will be used all over the
	15	world and in many different environments so local language dialects might
	16	confuse someone else.
36c24f4f	17
390372b4	18	File Structure
	19	==============
	20
efb05555	21	All translated files should be placed under the help directory. Under the
1e63b430	22	help directory create another directory. This directory MUST be named in the
efb05555	23	two letter standard abbreviation for the language. English is "en" and Polish
efb05555	24	would be "pl" for example.
390372b4	25
	26	The help files are written in a basic xml format. Don't worry, XML isn't hard
	27	at all. All it does is contain values inside tags like <start> and </start>.
	28	For these help files, the tags must be on their own line like this:
	29	<tag>
	30	Value for this tag
	31	</tag>
	32
	33	There are two types of main tags: <chapter> and <section>. There can be only
	34	one <chapter> tag in a .hlp file. However, there can be many <section> tags.
1e63b430	35	Inside each of these tags, there can be any combination of any of the following
390372b4	36	tags: <title>, <description>, <summary>. Here is an example:
	37
	38	\| <chapter>
	39	The title can only \| <title>
	40	be one line long \| My first chapter
	41	\| </title>
	42	Summary may be many \| <summary>
	43	lines, but is short \| Just a brief summary
	44	\| </summary>
	45	\| <description>
	46	Description can be \| This is a more detailed description that
	47	very long. It is \| can span many lines. Usually this is the
	48	the main part of \| bulk of the help section or chapter description.
	49	the help section. \| </description>
	50	\| </chapter>
	51
	52
	53	Translating
	54	===========
	55
1e63b430	56	To translate, just copy all the .hlp files from help/en into the new directory
390372b4	57	that you created for this language (i.e. help/pl). You only need to translate
1e63b430	58	what is between the tags. Do not translate the actual tags such as <chapter>
390372b4	59	or <summary>. The tag names need to remain in English. You should only translate
f4991a86	60	the text between tags.
390372b4	61
	62	Often there may be other HTML tags such as <b> for bold or <a href...> to make
	63	a link. If you see any of these tags, just leave them and don't translate
	64	them either. Only what is contained inside them if needed.
	65
	66	That should be all!!