====== Plugins & Languages (I18N) ======

If you display texts in your plugin, the easiest way is hardcode the texts in your plugin, e.g.:

<code php>
<input type="submit" name="save" value="Save Settings"/>
</code>

If this is within a admin back-end functionality this is fine at first, but if a lot of people use your plugin, you might want to think about internationalization (i18n), that is displaying the texts in the language of the user.

The easiest way is to reuse the translations of GetSimple itself. They can be found in the directory ''/path_to_getsimple/admin/lang'' and downloaded from [[http://get-simple.info/extend/|Extend]]. In our example you could use the key BTN_SAVESETTINGS:

<code php>
<input type="submit" name="save" value="<?php i18n("BTN_SAVESETTINGS"); ?>"/>
</code>

If your plugin also supports GetSimple 2.03, you would rather have to use:

<code php>
<?php global $i18n; ?>
<input type="submit" name="save" value="<?php $i18n["BTN_SAVESETTINGS"]; ?>"/>
</code>

A (not necessarily up-to-date) list of the built in i18n hashes can be found [[i18nhashes|on this page]].  Always check the source for the latest.

If you need additional texts not found in the standard GetSimple translation files, you need to create translation files yourself. They should look like the GetSimple translation files, e.g. de_DE.php:

<code php>
$i18n = array(
  'BTN_SAVEMYSETTINGS' => 'Meine Einstellungen speichern',
  'MYHEADER' => 'Meine Überschrift'
);
</code>

Put all your plugin specific language files into the directory ''my_plugin/lang/'', thus giving you a plugin with the following files:

<code>
- my_plugin.php
- my_plugin (directory)
   - .htaccess (with one line: Deny from all)
   - lang (directory) 
      - .htaccess (with one line: Deny from all)
      - en_US.php
      - de_DE.php
      - it_IT.php
</code>

GetSimple 3.0 makes it easy to load these texts in your plugin, e.g.:

<code php>
i18n_merge('my_plugin') || i18n_merge('my_plugin','en_US');
</code>

This will try to get the translations for the current admin language, and - if this fails - load the english texts. You need to make sure that the default language (here ''en_US'') texts do exist, e.g. ''my_plugin/lang/en_US.php''.

You then access them in the same way as standard GetSimple texts, but add your plugin name as prefix to the key, e.g.

<code php>
<input type="submit" name="save" value="<?php i18n("my_plugin/BTN_SAVEMYSETTINGS"); ?>"/>
</code>

Note that //i18n()// echos the translation.  If you need to use the translated text in php code you will have to use //i18n_r()// to return the string rather than echoing it, e.g.

<code php>
$msg = '<div style="display: block;" class="updated">' . i18n_r("my_plugin/MSG_UPDATED") . '.</div>';
echo $msg;
</code>

That's it. Just provide at least one language file (preferably english - ''en_US'') and wait for the community to provide translations into other languages, then include them in your plugin.


===== Language files without country =====

If you want to provide language files en.php, de.php, etc. (without country code), then use the following lines to load your texts:

<code php>
global $LANG;
i18n_merge('my_plugin', substr($LANG,0,2)) || i18n_merge('my_plugin','en');
</code>

===== Front-end =====

If your plugin has to display texts on the front-end (the internet site itself) and you just support typical GetSimple installations, where the content is displayed in one language and the admin back-end is set to this language, you do it the same way as described above.

The only difference is that you must provide language support, because where it might be acceptable for administrators and editors to see some information in english instead of their own language, it is unacceptable on the front-end. Without language support you basically limit your plugin to use in countries with the same language as yours.

**GetSimple 3.0:**

In the frontend the variable $LANG is always en_US (due to the multi-user capabilities introduced with 3.0). The user should be encouraged to enter a line 
<code>
$LANG = 'de_DE';
</code>
or similar into gsconfig.php.
As an alternative the plugin can offer a functionality to set the frontend language.

===== Multi-language Front-end =====

Some internet sites implemented with GetSimple support multiple languages. The language is determined from the user's preferences (his operating system language resp. the browser language) and he might be allowed to switch between the supported languages.

As multi-language sites are not supported natively by GetSimple, there currently exists one plugin, [[http://get-simple.info/extend/plugin/i18n/69/|I18N]].

If your plugin should support multi-language sites using the I18N plugin, you must load the texts **only after the I18N initialization** (in the pretemplate hook) - in your function(s) that output text on the front end, with

<code php>
global $LANG;
if (function_exists('i18n_load_texts')) {
  i18n_load_texts('my_plugin');
} else {  
  i18n_merge('my_plugin', substr($LANG,0,2)) || i18n_merge('my_plugin', 'en');
}
</code>

If you need back end template texts directly when loading the plugin, you need to check, if the plugin is loaded in the backend:

<code php>
if (basename($_SERVER['PHP_SELF']) != 'index.php') { // back end only - or do you know a better condition?
  i18n_merge('my_plugin', substr($LANG,0,2)) || i18n_merge('my_plugin', 'en');
}
add_action('plugins-sidebar', 'createSideMenu', array($thisfile, i18n_r('my_plugin/CONFIGURE'))); 
</code>

This code will work (with GetSimple 3.0+), whether the I18N plugin is present or not.

Note: the function i18n_load_texts is available in the I18N plugin 1.0+.

Note: The I18N plugin currently only supports language codes without country, so you must have language files like ''en.php'', ''de.php'' etc. instead of ''en_US.php'', etc.

NOte: The I18N plugin's current i18n_load_texts function might not be perfect yet. For a complete guide to using language files in the frontend, check out http://get-simple.info/forums/showthread.php?tid=1221&pid=56863#pid56863