Difference between revisions of "Languages - How to add or change phrases used by the forum software"

From Online Manual

Jump to: navigation, search
m (Corrected one misspelling of 'found'.)
 
(7 intermediate revisions by one other user not shown)
Line 1: Line 1:
With software used around the world, by many different peoples, in many different languages - such as SMF, it's always important to make the interface as easily and seamlessly translatable as possible. As such, this is one of the goals of themes.
+
This page explains how to work with language files and strings in SMF
  
===Language Files? Strings?===
+
===Defining Language Files and Strings===
Language files are simple groupings of language strings, or in other words phrases and sentences, meant to make it easier to link templates, sub templates, and language strings together. For performance and scope reasons (meaning, because sometimes it's better this way anyway) not every string is available to every template - they are only available by the "loaded" language files.
+
Language files are simple groupings of language strings, the words, phrases, and sentences, which are meant to make it easier to link templates, sub templates, and language strings together. For performance and scope reasons not every string is available to every template, instead they are only available through the "loaded" language files.
  
Generally speaking, language files are loaded with the same names as the templates they are used in. There are exceptions to this, such as Login being used by Register, but they are generally logical.
+
Generally speaking, language files are loaded with the same names as the templates in which they are used. There are exceptions to this, such as Login being used by Register, but the majority follows the general rule.
  
There is one special language file, which is "Modifications". This language file is meant mainly for packages and modifications, but it can also be used to specify more strings in many cases.
+
There is one special language file which is called "Modifications". This language file is meant mainly for packages and modifications, but it can also be used to specify more strings in many cases.
  
The language strings themselves are the "cream filling"; for example, a phrase such as "Send this Topic to a friend" could be one such language string. Every language string has an identifier, and for ease of use these are, for the most part, short terse english strings explaining the purpose of the string.
+
The language strings themselves are the "cream filling"; for example, a phrase such as "Send this Topic to a friend" could be a language string. Every language string has an identifier, and for ease of use these are, for the most part, short English strings explaining the purpose of the string.
  
The format is, for the most part, prefix_string_name. The above example might have the identifier 'sendtopic_to_friend'. This serves the purpose of grouping it (it's part of the sendtopic functionality) and labeling it.
+
The format is, for the most part, prefix_string_name. The above example might have the identifier 'sendtopic_to_friend'. This serves the purpose of grouping it (it is part of the sendtopic functionality) and labelling it.
  
===Great! So how do I use language strings?===
+
===How to Use Language Strings===
The fact that SMF uses language strings is all well and good, but what does that mean to you? If you use english in your theme, will that get automatically translated for you? Heh, we wish. No, you have to specifically use it in your theme - this means no english phrases :/. To have strings also available in languages like German or Thai, you will need the $txt variable. This is a lot like $context, except that it stores only a list of language strings available. To use our above example, you might use something like $txt['sendtopic_to_friend']. In your template, it would look a bit like this:
+
SMF's language strings allows translation into other languages without modifying templates or source files. but if the string is not translated into another language it will default to showing the English version. If you want a string to be translated you need to use the $txt variable. This is similar to how you would use $context, with the only difference being that it stores your language string instead.
 +
 
 +
Using the previous example, you might use something like $txt['sendtopic_to_friend']. In your template, it would look a bit like this:
 
{{code|1=<nowiki><b>', $txt['sendtopic_to_friend'], '</b></nowiki>}}
 
{{code|1=<nowiki><b>', $txt['sendtopic_to_friend'], '</b></nowiki>}}
As you can see, the identifier goes inside the brackets after $txt, surrounded by single quotes - just like contextual data. You have to use the ', ... , ' format to separate the string from regular text, though, as well.
 
  
===But, how do I use a language string not in the default set...===
+
As you can see, the identifier is placed between single quotes and inside square brackets after $txt, just as you would with contextual data, but you also have to use the ', ... , ' format to separate the string from regular text.  
With themes that really change the look of SMF, this is inevitable. It is for this reason specifically that language files can be tied directly to themes, not to the entire forum.
 
  
Just like templates, if you include a language file in your theme, it will be loaded from your theme, but if it isn't there it won&'t be. Here's the rule with language files:
+
===How to use a Language String Not in the Default Set===
 +
Themes which significantly alter SMF will often introduce new language strings. It is for this reason that language files are tied directly to themes rather than to the entire forum.
  
# Is there a *language file*.*user's language*.php in this theme?
+
If a custom theme is being used, SMF will check that theme's language folder to see if the file exists.  If the file does not exist, SMF will fall back on the default theme. Similarly, SMF will also check the user's language file.  If that file is not found, SMF will default to English.  For example, if file x.spanish.php is not found in the custom themes folder, SMF will check for x.english.php. If both of these are not found, SMF will search for x.spanish.php in the default themes language folder.  If this is not found, SMF will use x.english.php, which should always be found.
# Is there a *language file*.*forum language*.php in this theme?
 
# Is there a *language file*.*user's language*.php in the default theme?
 
# Is there a *language file*.*forum language*.php in the default theme?
 
  
However, if the forum's default language is Spanish, and you only have English available, it will end up falling back on the default language files.
+
When writing a theme, it is sometimes necessary to add new language files. To do this, you need to find the following code in index.template.php and change it to true:
 +
 
 +
{{code|1=<nowiki><?php
 +
//Set the following variable to true if this theme requires the optional theme strings file to be loaded.
 +
$settings['require_theme_strings'] = false;?></nowiki>}}
  
It is for this reason that it is sometimes necessary to add new language files. This helps make it clear that a new language file is needed for this theme, and that the default ones - even translated - will not do. To load a new language file, you will need to open your index template. Look for the "init" sub template, which can be found by searching for "template_init". This is a special initialization sub template. Right before the closing curly brace (}), add the following: loadLanguage('Theme'); And you're all set! The file, Theme.somelang.php might look like this:
+
The file, Theme.somelang.php might look like this:
 
{{code|1=<nowiki><?php
 
{{code|1=<nowiki><?php
 
// Version: 1.0 ; Theme
 
// Version: 1.0 ; Theme
 
$txt['mytheme_hello'] = 'How are you today?';
 
$txt['mytheme_hello'] = 'How are you today?';
 
?></nowiki>}}
 
?></nowiki>}}
It's recommended you use Theme, just because this makes it easier to tell which language file is yours for translators. You might want to look at some other language files, and other themes, to understand this better.
 
 
===Some notes to remember...===
 
A very important note is that if you want something like "don't", you need to use a \ to "escape" the '. See, If I said 'don't', it would be confusing... do I mean 'don' + t', or 'don't'? To "escape" this problem (pun intended) you just use 'don\'t'.
 
 
When translating, especially, you may need to use a special character, such as Å. Because of html validity, issues with PHP, and other things, it's best for you to instead use entities - these are like Å. Note that some strings should not have entities in them, and they should be noted as such. A list of entities can be found at:
 
 
http://www.w3schools.com/html/html_entitiesref.asp (the entity name is preferred.)
 
 
To change the character set and language code, you will need to modify your index.languagename.php file. In it, you should set $txt['lang_locale'] to the locale (short language identifier) and $txt['lang_character_set'] to the character set to be used. As well, $txt['lang_rtl'] needs to be = true if the language is read from right to left (rtl). For information on these, please look at the following references:
 
 
http://www.w3.org/International/O-charset-lang.html
 
 
http://www.w3.org/International/O-charset-list.html
 
 
http://msdn.microsoft.com/workshop/author/dhtml/reference/charsets/charset4.asp
 
 
Some other guidelines to follow for better internationalization (a fancy word for translatability):
 
 
*Whenever possible, try not to force word order. This means, don't take two strings and put them together - like 'How are ' . 'you'... this will make it harder to translate.
 
*Remember that some words have more than one meaning in English, but don't in other languages. Try to avoid using a word as a verb and a noun in different places.
 
*Be aware that some other languages may have very different rules for dates and pluralization than your native language.
 
  
See also: http://www.mozilla.org/docs/refList/i18n/
+
===Some Notes to Remember===
 +
#If you want to use a contraction like "don't" in a language string, you need to use \ to avoid the '. If you were to write 'don't', it would be confusing because it could mean 'don' + t', or 'don't'? To prevent this problem from occurring you use 'don\'t'.
 +
#When translating, you may need to use a special character, such as Å. However, owing to html validity and issues with PHP, it is best to use entities instead of these special characters. Note that some strings should not have entities in them and they should be noted as such.
 +
#Whenever possible, try not to force word order. This means avoiding putting two strings together.  An example would be 'How are ' . 'you'.  Having a string like this would make it harder to translate.
 +
#Remember that some words have more than one meaning in English, but not in other languages.
 +
#Try to avoid using a word as a verb and a noun in different places.
 +
#Be aware that some languages may have very different rules for dates and pluralisation than your native language.
  
 
Hopefully this will help you on your way to making themes that are different, wonderfully unique, and above all translatable - our non-English users thank you!
 
Hopefully this will help you on your way to making themes that are different, wonderfully unique, and above all translatable - our non-English users thank you!
  
 
[[Category:FAQ]]
 
[[Category:FAQ]]

Latest revision as of 07:43, 14 April 2016

This page explains how to work with language files and strings in SMF

Defining Language Files and Strings

Language files are simple groupings of language strings, the words, phrases, and sentences, which are meant to make it easier to link templates, sub templates, and language strings together. For performance and scope reasons not every string is available to every template, instead they are only available through the "loaded" language files.

Generally speaking, language files are loaded with the same names as the templates in which they are used. There are exceptions to this, such as Login being used by Register, but the majority follows the general rule.

There is one special language file which is called "Modifications". This language file is meant mainly for packages and modifications, but it can also be used to specify more strings in many cases.

The language strings themselves are the "cream filling"; for example, a phrase such as "Send this Topic to a friend" could be a language string. Every language string has an identifier, and for ease of use these are, for the most part, short English strings explaining the purpose of the string.

The format is, for the most part, prefix_string_name. The above example might have the identifier 'sendtopic_to_friend'. This serves the purpose of grouping it (it is part of the sendtopic functionality) and labelling it.

How to Use Language Strings

SMF's language strings allows translation into other languages without modifying templates or source files. but if the string is not translated into another language it will default to showing the English version. If you want a string to be translated you need to use the $txt variable. This is similar to how you would use $context, with the only difference being that it stores your language string instead.

Using the previous example, you might use something like $txt['sendtopic_to_friend']. In your template, it would look a bit like this:

<b>', $txt['sendtopic_to_friend'], '</b>

As you can see, the identifier is placed between single quotes and inside square brackets after $txt, just as you would with contextual data, but you also have to use the ', ... , ' format to separate the string from regular text.

How to use a Language String Not in the Default Set

Themes which significantly alter SMF will often introduce new language strings. It is for this reason that language files are tied directly to themes rather than to the entire forum.

If a custom theme is being used, SMF will check that theme's language folder to see if the file exists. If the file does not exist, SMF will fall back on the default theme. Similarly, SMF will also check the user's language file. If that file is not found, SMF will default to English. For example, if file x.spanish.php is not found in the custom themes folder, SMF will check for x.english.php. If both of these are not found, SMF will search for x.spanish.php in the default themes language folder. If this is not found, SMF will use x.english.php, which should always be found.

When writing a theme, it is sometimes necessary to add new language files. To do this, you need to find the following code in index.template.php and change it to true:

<?php
//Set the following variable to true if this theme requires the optional theme strings file to be loaded.
$settings['require_theme_strings'] = false;?>

The file, Theme.somelang.php might look like this:

<?php
// Version: 1.0 ; Theme
$txt['mytheme_hello'] = 'How are you today?';
?>

Some Notes to Remember

  1. If you want to use a contraction like "don't" in a language string, you need to use \ to avoid the '. If you were to write 'don't', it would be confusing because it could mean 'don' + t', or 'don't'? To prevent this problem from occurring you use 'don\'t'.
  2. When translating, you may need to use a special character, such as Å. However, owing to html validity and issues with PHP, it is best to use entities instead of these special characters. Note that some strings should not have entities in them and they should be noted as such.
  3. Whenever possible, try not to force word order. This means avoiding putting two strings together. An example would be 'How are ' . 'you'. Having a string like this would make it harder to translate.
  4. Remember that some words have more than one meaning in English, but not in other languages.
  5. Try to avoid using a word as a verb and a noun in different places.
  6. Be aware that some languages may have very different rules for dates and pluralisation than your native language.

Hopefully this will help you on your way to making themes that are different, wonderfully unique, and above all translatable - our non-English users thank you!