View source for Patterns and Strategies for Addons in XMB 1.9.11

There is a new translation API in the next version of XMB. This enables you (if you use it) to add $lang keys programmatically so that it is not an extra step in the hack installation.  The board admin will be free to edit your translations in the XMB admin panel as soon as the hack is installed and running.

==Adding $lang Keys in XMB 1.9.11==

===Square One: A Simple Translation Pattern===

This part of your hack should follow a simple pattern:

# Test for the last $lang key that your hack needs.
# When step 1 fails, require the translation.inc.php file.
# Call function setNewLangValue() for every $lang key that your hack needs.
# Call function loadLang() to reload the $lang array with the new settings.

Here is a simple example:

<pre>
if (!isset($lang['myhack_zblah'])) {
    require_once(ROOT.'include/translation.inc.php');
    setNewLangValue('myhack_hello', 'Hello World!');
    setNewLangValue('myhack_ohbye', 'Leaving so soon?');
    setNewLangValue('myhack_zblah', 'Nonsense &gt;_&gt;');
    loadLang($langfile);
}
</pre>

For more complex hacks that include their own multi-language translations (this is rare) you would have to check the $langfile value before adding keys.


===Level Two: For Large Translations===

This pattern is more flexible and more efficient. Whether you decide to use it will depend on the size of the translation and your proficiency with PHP. More knowledge of arrays and variable scope will be needed to deal with this in some cases.

<pre>
if (!isset($lang['myhack_zblah'])) {
    require_once(ROOT.'include/translation.inc.php');
    $phrases = array();
    $phrases['myhack_hello'] = 'Hello World!';
    $phrases['myhack_ohbye'] = 'Leaving so soon?';
    $phrases['myhack_zblah'] = 'Nonsense &gt;_&gt;';
    setManyLangValues($phrases, $langfile);
    loadLang($langfile);
}
</pre>

The most advanced use of this function so far is in version 6.0 of the Portal System. That hack is designed with many new phrases as well as its own translation files for multiple language support.


==Translation Strategies==

After updating just a few hacks for version 1.9.11, we saw that there were several different translation strategies that may be employed for performance and ease of installation.

===One-Page Hacks===

The most compact type of hack is the type that only modifies a single XMB script file. A perfect example is the XMBForum Support Form   This hack makes changes to the post.php file and a few templates only. So there is no sense in messing around with other files just to accomplish our translation needs. We simply add the translation to post.php itself. Here is a simplified snippet:

<pre>
if (!isset($lang['support_xmbversion'])) {
    require_once(ROOT.'include/translation.inc.php');
    $phrases = array();

    if ($langfile == 'Dutch') {
        $phrases['support_xmbversion'] = "XMB Versie";
    } elseif ($langfile == 'Serbian') {
        $phrases['support_xmbversion'] = "XMB Verzija";
    } elseif ($langfile == 'Spanish') {
        $phrases['support_xmbversion'] = "XMB Versión";
    } else {
        $phrases['support_xmbversion'] = "XMB Version";
    }

    setManyLangValues($phrases, $langfile);
    loadLang($langfile);
}
</pre>

The benefits of this strategy are that it puts all of our PHP code into one file, and it minimizes installation time by limiting the number of edits. Notice we no longer have to make changes to several lang.php files! 

===Multi-Page Hacks===
A different strategy is needed for hacks that change multiple XMB scripts. If we were to paste the translation into only one file, then there would be no guarantee that the other scripts would have the necessary phrases loaded. And of course we want to avoid pasting our translation into more than one file. A perfect example of the strategy for this type of hack is in Member Approval.  That hack modifies several files including member.php, post.php, cp.php, etc. All we need to do is include the translation one time inside of headers.php, like in this simplified example:

<pre>
=======
Step 7:
=======

============
Edit File: header.php
============

=========
Find Code :
=========

/* Set Up HTML Templates and Themes */

==============
Add Code Above:
==============

// Assert Member Approval Translation
if (!isset($lang['textapprovalsuccess'])) {
    require_once(ROOT.'include/translation.inc.php');
    $phrases = array();
    $phrases['textapproveselect'] = 'Not Approved';
    $phrases['textapprovalsuccess'] = 'Approval Successful!';
    setManyLangValues($phrases, $langfile);
    loadLang($langfile);
}
</pre>

This strategy has the advantage of making the new phrases available to every script in XMB without duplicating the translation code block.

===Templates-Only Hacks===
On my personal website, I have a custom hack that does not modify any of the XMB scripts. It merely adds extra translations that are specific to my website. Before version 1.9.11 I had to copy and paste them into every different lang.php file, what a pain! Now I have devised a much more convenient strategy as follows:

<pre>
============
Edit File: header.php
============

=========
Find Code :
=========

/* Set Up HTML Templates and Themes */

==============
Add Code Above:
==============

// Assert miqrogroove.com Translations
if (!isset($lang['maplink'])) {
    require(ROOT.'include/miqro.inc.php');
    miqro_translate();
}
</pre>

Here is a simplified version of my file named miqro.inc.php:

<pre>
<?php
if (!defined('IN_CODE')) {
    header('HTTP/1.0 403 Forbidden');
    exit("Not allowed to run this file directly.");
}

function miqro_translate() {
    global $langfile;

    require_once(ROOT.'include/translation.inc.php');
    
    $lang = array();
    $lang['maplink'] = "/links/english/";

    switch ($langfile) {
    case 'Estonian':
        $lang['maplink'] = "/links/eesti/";
        break;
    case 'Finnish':
        $lang['maplink'] = "/links/francais/";
        break;
    case 'German':
        $lang['maplink'] = "/links/deutsch/";
        break;
    case 'Italian':
        $lang['maplink'] = "/links/italiano/";
        break;
    case 'TraditionalChinese':
        $lang['maplink'] = "/links/chinese/";
        break;
    }

    setManyLangValues($lang, $langfile);
    loadLang($langfile);
}
?>
</pre>

This strategy has the advantage of making my personal translations very modular. Whenever I need to upgrade my board, I can install the new XMB scripts and translations with no worries. I will only need to edit header.php, and never again mess with all of those lang.php files.

===Very Large Hacks===
The Portal System for XMB 1.9.11 required yet another strategy because it is so large and because it includes translations in separate files like English.portal.php and Norsk.portal.php.

I needed to build a new Portal addition to the XMB translation API to make it work with multiple addon files. I named this addition portal.inc.php. For the sake of performance, portal.inc.php is included by each of the three scripts that are modified by the Portal hack. That assures all of the Portal translation logic is located in the separate files, and does not need to be loaded for every page in XMB.

The basic strategy of portal.inc.php is to include a *.portal.php file inside of a function where the global variable $lang is not in scope. Then the portal-only $lang array can be passed to the XMB translation function setManyLangValues() to finish the task.

===Editing the lang.php files===
This is a strategy that we hope to leave in the past. When a hack specifies changes to even one of these files, usually English.lang.php, it means that the webmaster who is installing the hack will have to make the same changes to any other languages that are installed. There are currently 25 official translation files in production for version 1.9.11. That number will continue to grow in the future, and believe me it is a pain to make global changes to those files.

Editing the translation files is of course possible, but highly discouraged for new hacks.