modules/language_sections/README.txt

$Id:

Language Sections module for Drupal 5.x and 6.x
===============================================

Description:

Language Sections is a simple "input filter" module to allow text sections in several languages to be stored in a single text field.  One typical application is with the "Views" module with its header, footer and "not found" text fields.


Applications:

This module was originally produced with "Views" in mind. It may also be useful wherever "input filters" are supported but multi-language support is unavailable or limited.  For example, you could display "This page is only available in English" at the top of a node when the user's chosen language was not set to English, or to display a link to a translated version of the same content.


Configuration:

Enable the module and activate it in one or more "Input Formats".  It should probably be the first or one of the first filters in the sequence, so set its "weight" to a low number.

Several advanced options are available in the "Configure" tab via admin/settings/filters. See the text
descriptions there for more information. 


Use:

Mark the start of "language sections" with === lc === where "lc" is an appropriate language code for the system.  No specific "end of section" marker is needed - any subsequent section is considered to mark the end of the preceding section. The pseudo-language-code "qq" can be used to represent "any language" - sections marked with "qq" will be displayed for all languages.  Text before the first language section will also be displayed for all languages.

Here's an example - this is the text as entered:
---------------------
This text will be displayed for all languages.
=== es ===
Some Spanish text goes here.
=== en ===
Some English text goes here.
=== qq ===
This part will be displayed for all languages.  
---------------------

When language "en" is selected by the user, the above text will be filtered to become:
---------------------
This text will be displayed for all languages.
Some English text goes here.
This part will be displayed for all languages.  
---------------------

When language "es" is selected by the user, the above text will be filtered to become:
---------------------
This text will be displayed for all languages.
Some Spanish text goes here.
This part will be displayed for all languages.  
---------------------

Any number of language sections can be used, e.g:
=== es ===
Some Spanish
=== en ===
Some English
=== es ===
Some more Spanish
... and so on ...

Note: Although three = characters are shown in these examples, any number can be used, and there may be no space or more than one space around the language code.  i.e. the following are both valid:
=======   en   =======
=es=

Language codes in the format aa-bb, such as en-uk, are also supported in the standard configuration. Other language code formats can be supported by modifying the regular expression used (configuration option.) 

"Default" section

A "default" section can be created by using the pseudo-language-code "qz". A default section will be output when no specific section was previously found for the current language. Therefore, the position of any default section(s) is important - they should be placed after language-specific sections.  For example, you might have language-specific sections in French, Spanish and German followed by a default section in English.

"Any language" section

A section marked with the pseudo-language-code "qq" will be output for any language, regardless of whether or not a language-specific section or default section has already been used.  For example, these sections might be used to include images, PHP code or other content which is language-neutral.

Single-line handling

A single line should also work, for example:
This is some =en= English =es= Spanish =qq= text.

Note:
If you use Language Sections to create multiple versions of the same content within the body of a single node, you should probably set the node itself to "no language".

Technical notes:

The "trigger" for a language section can be described as the following sequence:

1. one or more '=' characters, then
2. zero or more spaces, then
3. a language code in the format nn or nn-mm, then
4. zero or more spaces, then
5. one or more '=' characters.

This trigger sequence was chosen so as to be easy to use and easily readable in its raw form, at the risk of false triggering should text happen to contain a sequence matching the trigger sequence.

The regular expression pattern used for matching can be edited (configuration setting).  Be careful not to change the number of parenthesised groups, as that would probably break the logic used to identify individual sections.


Contact:

Andy Inman - drupal_dev(at)netgenius(dot)co(dot)uk

1	$Id:
2
3	Language Sections module for Drupal 5.x and 6.x
4	===============================================
5
6	Description:
7
8	Language Sections is a simple "input filter" module to allow text sections in several languages to be stored in a single text field. One typical application is with the "Views" module with its header, footer and "not found" text fields.
9
10
11	Applications:
12
13	This module was originally produced with "Views" in mind. It may also be useful wherever "input filters" are supported but multi-language support is unavailable or limited. For example, you could display "This page is only available in English" at the top of a node when the user's chosen language was not set to English, or to display a link to a translated version of the same content.
14
15
16	Configuration:
17
18	Enable the module and activate it in one or more "Input Formats". It should probably be the first or one of the first filters in the sequence, so set its "weight" to a low number.
19
20	Several advanced options are available in the "Configure" tab via admin/settings/filters. See the text
21	descriptions there for more information.
22
23
24	Use:
25
26	Mark the start of "language sections" with === lc === where "lc" is an appropriate language code for the system. No specific "end of section" marker is needed - any subsequent section is considered to mark the end of the preceding section. The pseudo-language-code "qq" can be used to represent "any language" - sections marked with "qq" will be displayed for all languages. Text before the first language section will also be displayed for all languages.
27
28	Here's an example - this is the text as entered:
29	---------------------
30	This text will be displayed for all languages.
31	=== es ===
32	Some Spanish text goes here.
33	=== en ===
34	Some English text goes here.
35	=== qq ===
36	This part will be displayed for all languages.
37	---------------------
38
39	When language "en" is selected by the user, the above text will be filtered to become:
40	---------------------
41	This text will be displayed for all languages.
42	Some English text goes here.
43	This part will be displayed for all languages.
44	---------------------
45
46	When language "es" is selected by the user, the above text will be filtered to become:
47	---------------------
48	This text will be displayed for all languages.
49	Some Spanish text goes here.
50	This part will be displayed for all languages.
51	---------------------
52
53	Any number of language sections can be used, e.g:
54	=== es ===
55	Some Spanish
56	=== en ===
57	Some English
58	=== es ===
59	Some more Spanish
60	... and so on ...
61
62	Note: Although three = characters are shown in these examples, any number can be used, and there may be no space or more than one space around the language code. i.e. the following are both valid:
63	======= en =======
64	=es=
65
66	Language codes in the format aa-bb, such as en-uk, are also supported in the standard configuration. Other language code formats can be supported by modifying the regular expression used (configuration option.)
67
68	"Default" section
69
70	A "default" section can be created by using the pseudo-language-code "qz". A default section will be output when no specific section was previously found for the current language. Therefore, the position of any default section(s) is important - they should be placed after language-specific sections. For example, you might have language-specific sections in French, Spanish and German followed by a default section in English.
71
72	"Any language" section
73
74	A section marked with the pseudo-language-code "qq" will be output for any language, regardless of whether or not a language-specific section or default section has already been used. For example, these sections might be used to include images, PHP code or other content which is language-neutral.
75
76	Single-line handling
77
78	A single line should also work, for example:
79	This is some =en= English =es= Spanish =qq= text.
80
81	Note:
82	If you use Language Sections to create multiple versions of the same content within the body of a single node, you should probably set the node itself to "no language".
83
84	Technical notes:
85
86	The "trigger" for a language section can be described as the following sequence:
87
88	1. one or more '=' characters, then
89	2. zero or more spaces, then
90	3. a language code in the format nn or nn-mm, then
91	4. zero or more spaces, then
92	5. one or more '=' characters.
93
94	This trigger sequence was chosen so as to be easy to use and easily readable in its raw form, at the risk of false triggering should text happen to contain a sequence matching the trigger sequence.
95
96	The regular expression pattern used for matching can be edited (configuration setting). Be careful not to change the number of parenthesised groups, as that would probably break the logic used to identify individual sections.
97
98
99	Contact:
100
101	Andy Inman - drupal_dev(at)netgenius(dot)co(dot)uk
102