Submitted by UTF-8
One problem many people have is a bad text editor. phpBB 3.0 uses UTF-8 encoding on the language files. If you get all weird stuff while opening a language file, your editor probably doesn't support UTF-8, or you didn't open it in UTF-8 mode. If it doesn't support it, i suggest you get a proper editor, for example PSPad (freeware).
What is UTF-8? UTF-8 is a unicode encoding with variable character length. UTF-8 basicly means that you can use special characters such as » “ ”. phpBB 3.0 supports this for both posting and language system. Make sure you only edit language files using UTF-8.
Another thing that can cause problems is a BOM. A BOM is a "Byte-order mark", which is a special character that can be added to the top of a file to indicate that the file is UTF-8. For PHP this can cause problems and most "Headers already sent" PHP notices happen because of this. Because it sends this character to the browser, thus not allowing phpBB to send it's own headers. So in your editor, make sure you disable adding a BOM.
Create a language file
If we want to create our own language file (for a MOD), it will usually go into language/{lang}/mods/. Let's assume we are creating a pastebin. Usually all language keys are sorted and grouped alphabetically. Here is an example language file:
- Code: Select all
<?php
/**
*
* @package phpBB3
* @version $Id$
* @copyright (c) 2008 phpbbmodders
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
*/
if (!defined('IN_PHPBB'))
{
exit;
}
/**
* DO NOT CHANGE
*/
if (empty($lang) || !is_array($lang))
{
$lang = array();
}
/**
* Our pastebin
*/
$lang = array_merge($lang, array(
'NOT_INSTALLED' => 'The pastebin has not been installed.',
'PASTEBIN' => 'Pastebin',
'PASTEBIN_EXPLAIN' => 'The pastebin is a database of snippets.',
));
?>
You can ignore everything until * Our pastebin, but note that all of it is required. Below, you can see all the entries in the format 'KEY' => 'value',. Language keys are always uppercase. A language entry should be indented using tabs and it needs to have a comma at the end of the line. If you need to use the ' character, use UTF-8 characters instead. Here are some from language/{lang}/common.php that you can copy-paste:
- Code: Select all
// Some characters you may want to copy&paste:
// ’ » “ ” …
They were added by SHS’. This example language file would be saved as language/{lang}/mods/pastebin.php.
Load language files
When coding a page you'll have to load language files. Let's load the language file in our pastebin. For this there is a method (function) called user::load_lang. Alternativeley, you can pass it to user::setup().
As every phpBB 3.0 page, we need this at the top:
- Code: Select all
<?php
/**
*
* @package phpBB3
* @version $Id$
* @copyright (c) 2008 phpbbmodders
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = (defined('PHPBB_ROOT_PATH')) ? PHPBB_ROOT_PATH : './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'common.' . $phpEx);
// Start session management
$user->session_begin();
$auth->acl($user->data);
$user->setup();
Now instead of $user->setup() we could use:
- Code: Select all
$user->setup('mods/pastebin');
That would load the language/{lang}/mods/pastebin.php language file. For loading mutliple language files, we would do the following:
- Code: Select all
$user->setup(array('mods/pastebin', 'mods/pastebin1', 'mods/pastebin2'));
Now, if you want to load a language file after calling user::setup(), you have to use user::add_lang(), like this:
- Code: Select all
$user->add_lang('mods/pastebin3');
$user->add_lang(array('mods/pastebin4', 'mods/pastebin5'));
Using language keys
To use language keys, you simply access them like this:
- Code: Select all
$user->lang['LANG_KEY']
This is bareley needed though, because most language keys are used by the template.
Using language keys in the template
The language system in phpBB 3.0 is integrated with the template system, so unlike phpBB 2.0, you can access language keys without assigning them. To access a language variable, you use this in your template file:
- Code: Select all
{L_LANG_KEY}
This is how it's most commonly used.
Language file auto-inclusion
phpBB 3.0 has a modules system for the ucp/mcp/acp (user control panel/moderator control panel/administrator control panel). Because some MODs simply add a module, it would be a shame if they had to edit a language file just to add the language for the module menu language. For this reason, the phpBB developers added some code to auto include language files, if they follow the correct format.
First of all, the language file has to be either in language/{lang}/acp/ or language/{lang}/mods/.
Secondly, the language file must be named in following format: info_{class}_{custom}.php. {class} is the module class, this is either ucp, mcp or acp. {custom} can be anything, it should fit your MOD.
These files are then automatically included.
FAQ language files
The format of FAQ language files is slightly different. These files must be prefixed with help_. For an example look at language/{lang}/help_bbcode.php. They can only be loaded using user::add_lang(), the second argument must be false, the third true. The language is stored in $user->help. Look at faq.php for more info.
Lang keys with trigger_error()
The trigger_error() function is used by phpBB 3.0 to display errors and confirmation messages. The first argument is the error message, it is also possible to only give it a language key, for example:
- Code: Select all
trigger_error('NO_FORUM');
That would trigger the following error:
The forum you selected does not exist.