From e25d8bab650f2b15a78a481e8dabe81efcaf139f Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Sat, 15 Sep 2007 00:17:37 +0000 Subject: [PATCH] bfojcapell: Added i18n api comments (merged from branches/gsoc) git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@41832 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- core/Core.php | 15 ++++++++++-- core/i18n.php | 67 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 74 insertions(+), 8 deletions(-) diff --git a/core/Core.php b/core/Core.php index a59e4fc9b..d85ec20e7 100755 --- a/core/Core.php +++ b/core/Core.php @@ -85,13 +85,24 @@ function stripslashes_recursively(&$array) { /** * This is the main translator function. Returns the string defined by $class and $entity according to the currently set locale + * + * @param string $class Class where the entity was defined. It acts as a namespace. + * @param string $entity Entity that identifies the string inside the namespace. + * @param string $string The original string itself. In a usual call this is a mandatory parameter, but if you are reusing a string which + * has already been "declared" (using another call to this function, with the same class and entity), you can omit it. + * @param string $priority Optional parameter to set a translation priority. If a string is widely used, should have a high priority (PR_HIGH), + * in this way translators will be able to prioritise this strings. If a string is rarely shown, you should use PR_LOW. + * You can use PR_MEDIUM as well. Leaving this field blank will be interpretated as a "normal" priority (less than PR_MEDIUM). + * @param string $context If the string can be difficult to translate by any reason, you can help translators with some more info using this param + * + * @return string The translated string, according to the currently set locale {@link i18n::setLocale()} */ -function _($class, $entity, $string="", $priority=100, $context="") { +function _($class, $entity, $string="", $priority=40, $context="") { global $lang; $locale = i18n::getLocale(); $class = ereg_replace('.*([/\\]+)',"",$class); if (substr($class,-4) == '.php') $class = substr($class,0,-4); - if (!$lang[$locale][$class]) i18n::includeByClass($class); + if (isset(!$lang[$locale][$class])) i18n::includeByClass($class); $transEntity = $lang[i18n::getLocale()][$class][$entity]; return (is_array($transEntity) ? $transEntity[0] : $transEntity); } diff --git a/core/i18n.php b/core/i18n.php index 3adde5c5e..ab2e597c0 100755 --- a/core/i18n.php +++ b/core/i18n.php @@ -1,12 +1,30 @@ + */ + +/** + * Priorities definition. These constants are used in calls to _() as an optional argument + */ define('PR_HIGH',100); define('PR_MEDIUM',50); define('PR_LOW',10); class i18n extends Controller { - static $currentlocale = 'en'; + /** + * This static variable is used to store the current defined locale. Default value is 'en' + */ + static $currentlocale = 'en'; + + /** + * This is the main method to build the master string tables with the original strings. + * It will search for existent modules that use the i18n feature, parse the _() calls + * and write the resultant files in the lang folder of each module. + */ static function textCollector() { if (!Permission::check("ADMIN")) die("You must be an admin to enable text collector mode"); @@ -29,6 +47,12 @@ class i18n extends Controller { } + /** + * Searches for all the files in a given module + * + * @param string $baseDir Silverstripe's base directory + * @param string $module Module's name + */ private static function processModule($baseDir, $module) { if(is_dir("$baseDir/$module") && !in_array($module, array('sapphire','jsparty','assets')) && substr($module,0,1) != '.') { i18n::getFilesRec("$baseDir/$module/code", $fileList); @@ -60,6 +84,12 @@ class i18n extends Controller { } } + /** + * Helper function that searches for potential files to be parsed + * + * @param string $folder base directory to scan (will scan recursively) + * @param array $fileList Array where potential files will be added to + */ private static function getFilesRec($folder, &$fileList) { $items = scandir($folder); if($items) foreach($items as $item) { @@ -71,7 +101,11 @@ class i18n extends Controller { } /** - * Look for calls to the underscore function and build our MST + * Look for calls to the underscore function in php files and build our MST + * + * @param string $index Classname used to namespace strings + * @param string $file Path to the file to be parsed + * @return string Built Master String Table from this file */ private static function reportCallsCode($index, $file) { static $callMap; @@ -99,8 +133,12 @@ class i18n extends Controller { } /** - * Look for calls to the underscore function and build our MST + * Look for calls to the underscore function in template files and build our MST * Template version - no "class" argument + * + * @param string $index Index used to namespace strings + * @param string $file Path to the file to be parsed + * @return string Built Master String Table from this file */ private static function reportCallsTpl($index, $file) { static $callMap; @@ -126,18 +164,33 @@ class i18n extends Controller { return $mst; } + /** + * Set the current locale + * See http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html for a list of possible locales + * + * @param string $locale Locale to be set + */ static function setLocale($locale) { if ($locale) i18n::$currentlocale = $locale; } + + /** + * Get the current locale + * + * @return string Current locale in the system + */ static function getLocale() { return i18n::$currentlocale; } /** * Includes all available language files for a certain defined locale + * + * @param string $locale All resources from any module in locale $locale will be loaded */ static function includeByLocale($locale) { - $topLevel = scandir(Director::baseFolder()); + if (file_exists($file = Director::getAbsFile("cms/lang/$locale.php"))) include_once($file); + $topLevel = array_diff(scandir(Director::baseFolder()),array('cms')); foreach($topLevel as $module) { if (file_exists($file = Director::getAbsFile("$module/lang/$locale.php"))) { include_once($file); @@ -148,7 +201,9 @@ class i18n extends Controller { /** * Given a class name (a "locale namespace"), will search for its module and, if available, * will load the resources for the currently defined locale. - * If not available, the original english resource will be loaded instead (to avoid blanks) + * If not available, the original English resource will be loaded instead (to avoid blanks) + * + * @param string $class Resources for this class will be included, according to the set locale. */ static function includeByClass($class) { if (substr($class,-3) == '.ss') { @@ -160,7 +215,7 @@ class i18n extends Controller { global $_CLASS_MANIFEST; $path = $_CLASS_MANIFEST[$class]; ereg('.*/([^/]+)/code/',$path,$module); - }//die($class); + } if (file_exists($file = Director::getAbsFile("{$module[1]}/lang/". i18n::getLocale() . '.php'))) { include_once($file); } else if (i18n::getLocale() != 'en') {