View source for Using the SMF language system in your mods

View source for Using the SMF language system in your mods From Online Manual

← Using the SMF language system in your mods
Jump to: navigation, search
You do not have permission to edit this page, for the following reason:
The action you have requested is limited to users in one of the groups: Users, SMF_Team_Members.
You can view and copy the source of this page.
SMF has a powerful language system that supports the user of using one or more international languages on your forum. There are many languages packs available on the SMF website and many international communities are using SMF, despite the fact that it was original written in English.

SMF is able to do this this through the use of language files. SMF finds the language the user has selected and calls the appropriate language files to use. There are no hardcoded language strings present in the SMF templates. This means you won't ever see something like: <code><nowiki>echo ' <div>This is text, are you text?</div>';</nowiki></code> in any template, but rather a variable that holds the text inside of it. So assuming <code><nowiki>$txt['this_is_text']</nowiki></code> held the string for what was used above, the call to the text in the template would then look like this: 
{{code|1=<nowiki>echo ' <div>', $txt['this_is_text'], '</div> ';</nowiki>}}
All mods should make use of SMF's language system. Not just for making it easy for international communities to translate the text in your mod, but also because it can often cut down on repetitive text that is used in more than one place.

This is an overview of how you use the language system in SMF and is advised to follow, especially since in the not too far future, mods may not be accepted that do not use language files. For starters, languages are stored in this fashion: Themes/default/languages/filename.languagename.php. So for example the most important language file for the english version (included in the default SMF install) is found in Themes/default/languages/index.english.php.

There are two possible ways to include your language strings for your mod. You can apply the language strings to the end of the Modifications.english.php file or create your own language file to store in Themes/default/languages.

==How to create language variables==
We won't worry about where we are going to put these until later, but a normal language variable is assigned in this fashion:

{{code|1=<nowiki>$txt['name_of_string'] = 'Look at me!';</nowiki>}}Notice the use of $txt. The variable isn't required to be called $txt, but should because there is no need to have more variables globalized when $txt is available in every function used in SMF. The next part... ['name_of_string'] is the identifier used for the language variable. One important thing to note, is that you have to escape single quotes with backslashes or you will get parse errors causing the page not to work.

{{code|1=<nowiki>$txt['parse_error'] = 'This 'cool' example will result in a parse error'; // bad, won't work.
$txt['no_parse_error'] = 'This \'cool\' example will work'; // good, will work.</nowiki>}}
==When and how to use Modifications.english.php==
Modifications.english.php is a very useful file to use for mods to add language strings too. Like index.english.php, this file is loaded at all times so you do not need to worry about a language variable not being defined for use in one of your templates. However, in some cases it may be desired to have your mod use your own language file instead. If your mod only really touches one page, but uses a lot of language strings, it may not be the best thing to have the mod's language strings loaded on every page when they only need to be loaded on one page.

==When and how to use CustomFile.english.php==
SMF has a function called loadLanguage('filename') that will load a language file for use. Often it is useful to use your own language file for a mod. If the mod only touches a set of pages, and you want all the the language strings in one organized location, you can create your own language file to use. When you load your custom language file, you should ALWAYS do it in the source file for your mod. That is of course, assuming your mod uses the familiar SMF style of: source file / template file for a page.

The loadLanguage() should be called when it is needed, and if no $txt variables from your language file are needed for the source file you load it on, you could even call it at the very end, making sure a function isn't returned before it is called though. It is best to call it after the major checks to make sure the user can access the page, as it may not be needed if the user is denied access, unless of course the error message to be outputted is from your language file. The parameter that the loadLanguage() function takes is the filename for the language you are loading. So if your custom language file is in: Themes/default/languages/mycustomlanguagefile.php would use loadLanguage('mycustomlanguagefile');

Example usage:

{{code|1=<nowiki><?php

function MyMod()
{
// Are we allowed to see this? 
isAllowedTo('admin_forum');

// Did we get the parameter we wanted?
if(!isset($_REQUEST['msg']))
fatal_lang_error('error');

// Now we can load the language file we want as it will now be needed.
loadLanguage('mycustomlanguagefile');

// What the language strings will be used on.
loadTemplate('mycustomtemplatefile');
}

?></nowiki>}}

==Using the strings assigned in language files in the template==
Mentioned early was how you could actually use your language strings in the template, but here is some more explanation. Language strings are called just like any variable is called in php, so if you have some php knowledge, this should not be new to you. The key thing to look out for is the "echo" piece of code. echo is the language construct in php that outputs text to the browser. In php a string of text is always represented in an opening and closing single quote (' ') or double quote (" "). In SMF, single quotes are used, so we will explain how to use them. Look at the following:

{{code|1=<nowiki>echo ' I am a text string';
$variable['text'] = 'I am a text string';
echo $variable['text']; // Is the same as above... echo ' I am a text string';
echo ' ', $variable['text'], ' '; // Will also work, and is normally best to use.
Take a look at the third example:
{{code|1=<nowiki>echo ' ', $variable['text'], ' '; 
It may look the most confusing, but is normally the fastest way to do it and works well when it is used inside of html code.
{{code|1=<nowiki>echo ' <table><tr><td>', $txt['hello'], '</td></tr></table>'; // Method 1
echo ' <table><tr><td> . $txt['hello'] . </td></tr></table>'; // Method 2</nowiki>}}
The second method requires the string being outputted to be concatenated together, which is a little slower. So the important thing to understand is that whenever you call your language variable it needs to be in a fashion that it it has a single quote and comma like this: ', $var ,' when used with the echo ' TEXT HERE '; fashion and would need to be like: echo $hello_world . $var; if the echo does not start and end with a closing single quote.

===Getting used to it===

Try taking a look at the index.template.php file to get use to and understand how language variables are used:

{{code|1=<nowiki> // Show a random news item? (or you could pick one from news_lines...)
if (!empty($settings['enable_news']))
echo '
<td width="90%" class="titlebg2">
<span class="smalltext"><b>', $txt[102], '</b>: ', $context['random_news_line'], '</span>
</td>'; </nowiki>}}
[[Category:Developing SMF]]
[[Category:Coding with SMF]]
Templates used on this page:
Return to Using the SMF language system in your mods.
Retrieved from "https://wiki.simplemachines.org/smf/Using_the_SMF_language_system_in_your_mods"
Navigation

Search

Tools

View source for Using the SMF language system in your mods From Online Manual
