Contents 1 Overview 1.1 Keys 2 DEV-Mode Localization 2.1 DEV-Mode External Functions 2.2 DEV-Mode Callbacks 3 RT-Mode Localization 3.1 RT-Mode External Functions 3.2 RT-Mode Callbacks

Overview

There are two categories of HeroEngine Localization system external functions:

1. DEV-mode external functions, which support the creation of localized string databases while a game is under development, and
2. RT-mode external functions, which support the use of localized string databases when a game is being played (i.e., at the game's "runtime").

Keys

Localization callback external functions identify files and string tables by their keys. Both DEV-mode and RT-mode configuration files are identified by a special reserved key with the value 1.

DEV-Mode Localization

DEV-Mode External Functions

// Causes the development localization system to be initialized, the node specified is the controlling node for the localization system
//   and by default will be the $LOCALIZATION system node.
//
// callback_node: a GOM node upon which various system event methods are called
//
// returns FALSE, if the localization subsystem has already been started up, or is otherwise disabled or unusable
// returns TRUE, after the localization system has been started up
//
// causes SCRIPT ERROR if the callback_node is NONE
external function Loc_Startup( callback_node as NodeRef ) as Boolean
 
 
// Causes all dirty (or all) configuration, universe and development tables to be saved to the respository
//   causes callback events:
//     Loc_OnAPICallFailed( ... )
//     Loc_SingleFileCallback(...)
//     Loc_MultiFileCallback(...) 
external function Loc_SaveAllAsync( force_non_dirty_write as Boolean ) as Boolean 
// force_non_dirty_write: when TRUE, causes all files to be saved.  when FALSE, causes only files with changes to be saved.
//
// returns FALSE, never.
// returns TRUE, when saving has begun.
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Creates a new, empty configuration using the specified details.
//   causes callback events:
//     LOC_OnAPICallFailed(  ) failure conditions: a configuration is already loaded, a configuration is in the process of loading, invalid name, 
//                                                        invalid filename, invalid runtime filename
external function Loc_ConfigurationCreate( name as String, filename as String, runtime_filename as String ) as Boolean
// filename: the filename where this configuration will be saved to and loaded from in the repository
// runtime_filename: the filename where the runtime configuration data will be saved to in the repository
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
// Causes a configuration to be loaded from the repository
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: a configuration is already loaded, a configuration is in the process of loading, invalid filename, 
//                                                    missing file in repository, invalid or inconsistent data in specified file
//     Loc_SingleFileCallback(...)
external function Loc_ConfigurationLoadAsync( file_name as String ) as Boolean  
// file_name: the filename where this configuration will be loaded from and later saved to the repository
//
// returns TRUE, upon the start of the loading process
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
// Causes the currently loaded configuration to be unloaded from memory
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, the configuration has not yet completed loading,
//                                                    unsaved data exists in the configuration (any universe or string table)
external function Loc_ConfigurationUnload() as Boolean
// returns TRUE, upon the completion of the unloading process
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Causes a configuration to be unloaded from memory without checking for dirtiness
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration in memory, configuration has not yet completed loading
external function Loc_ConfigurationPurgeWithoutSaving() as Boolean
// returns TRUE, upon the completion of the purging process
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
// Causes a configuration and all of its universes, tables & string tables to be saved to the repository
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration in memory, configuration has not yet completed loading, error occurs while writing to repository
//     Loc_SingleFileCallback(...)
//     Loc_MultiFileCallback(...) 
external function Loc_ConfigurationSaveAsync() as Boolean  
// returns TRUE, upon the initiation of the saving process
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Changes the name of the configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, invalid name specified
external function Loc_ConfigurationNameSet( new_name as String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
// Changes the filename of the configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, invalid failename specified
external function Loc_ConfigurationFilenameSet( new_filename as String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Changes the runtime filename of the configuration
//   causes callback events:
//    LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, invalid failename specified
external function Loc_ConfigurationRuntimeFilenameSet( new_runtime_filename as String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Retrieves the current meta-data settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationMetaGet( meta_key_value_map_out references LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Establishes the current meta-data settings, replacing any former settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, any key or value string does not meet constraints
external function Loc_ConfigurationMetaSet( meta_key_value_map as LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Retrieves the current development parameter settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationDevParameterGet( parms_value_map_out references LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Establishes the current development parameter settings, replacing any former settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, any key or value string does not meet constraints
external function Loc_ConfigurationDevParameterSet( parms_value_map as LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Retrieves the current runtime parameter settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationRTParameterGet( parms_value_map_out references LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Establishes the current runtime parameter settings, replacing any former settings
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, any key or value string does not meet constraints
external function Loc_ConfigurationRTParameterSet( parms_value_map as LookupList indexed by String of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Adds a locale to the list of supported locales for this configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, locale does not meet constraints, locale is already in the list
external function Loc_ConfigurationLocaleAdd( locale_to_add as String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Removes a locale from the list of supported locales for this configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, locale does not meet constraints, locale is not in the list,  locale is in use on any loaded universe
external function Loc_ConfigurationLocaleRemove( locale_to_remove as String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Returns the list of supported locales for this configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... )  failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationLocaleList( locales_out references List of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Returns the list of universes and their general characteristics for this configuration
// causes callback events:
//   LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationUniverseList( universe_count_out references Integer, universe_keys_out references List of ID, universe_names_out references List of String, universe_range_lows_out references List of Integer, universe_range_highs_out references List of Integer, universe_filenames_out references List of String, universe_runtime_filenames_out references List of String ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Returns the description for this configuration.  The use of LOC_ConfigurationUniverseList and LOC_ConfigurationLocaleList
//   is used to return the detail information about Universes and Locales
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded
external function Loc_ConfigurationDescribe( name_out references String, filename_out references String, runtime_filename_out references String, universe_count_out references Integer, locale_count_out references Integer ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Creates a universe using the specified parameters
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, specified range is invalid, specified range overlaps another range in use, any constraing is violated
external function Loc_ConfigurationUniverseCreate ( name as String, filename as String, runtime_filename as String, range_low as Integer, range_high as Integer, universe_key_out references ID ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Removes a universe from the configuration
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, specified universe does not exist, specified universe is not loaded, specified universe is currently loading
external function Loc_ConfigurationUniverseRemove ( universe_key as ID ) as Boolean
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
// Begins loading the specified universe
//   causes callback events:
//     LOC_OnAPICallFailed( ... ) failure conditions: no configuration is in memory, configuration not yet loaded, specified universe does not exist, specified universe is not loaded, specified universe is currently loading,  
//                                                    repository file is not available, the repository file is malformed, the repository file is inconsistent with the universe's declaration in the configuration
//     Loc_SingleFileCallback(...)
external function Loc_UniverseLoadAsync( universe_key as ID ) as Boolean
// returns TRUE, upon beginning the loading process
// returns FALSE, if an error occurs
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
external function Loc_UniverseUnload( universe_key as ID ) as Boolean
// : causes the specified universe to be unloaded from memory
//
// returns TRUE, upon the completion of the unloading process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => unsaved data exists in the universe, any table, or any string table
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
 
external function Loc_UniversePurgeWithoutSaving( universe_key as ID ) as Boolean
// : causes a universe to be unloaded from memory without checking for dirtiness
//
// returns TRUE, upon the completion of the purging process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
external function Loc_UniverseSaveAsync( universe_key as ID ) as Boolean  
// : causes the specified universe to be saved from memory to disk
//
// returns TRUE, upon beginning the saving process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the repository file can not be saved
//     Loc_SingleFileCallback(...)
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseNameSet( universe_key as ID, new_name as String ) as Boolean
// : sets the name of the specified universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseFilenameSet( universe_key as ID, new_filename as String ) as Boolean
// : sets (changes) the filename of the specified universe's saved file
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseRuntimeFilenameSet( universe_key as ID, new_runtime_filename as String ) as Boolean
// : sets (changes) the runtime filename of the specified universe's saved file
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
// TODO:  this may fold into universe describe
external function Loc_UniverseRangeGet( universe_key as ID, range_low references Integer, range_high references Integer ) as Boolean
// : gets the range of the specified universe string numbers
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully 
 
external function Loc_UniverseRangeSet( universe_key as ID, new_range_low as Integer, new_range_high as Integer ) as Boolean
// : sets (changes) the range of the specified universe string numbers
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the new range is invalid
//     => the new range overlaps any existing range
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseMetaGet( universe_key as ID, meta_key_value_map_out references LookupList indexed by String of String ) as Boolean
// : retrieves the current meta-data settings
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseMetaSet( universe_key as ID, meta_key_value_map as LookupList indexed by String of String ) as Boolean
// : establishes the current meta-data settings, replacing any former settings
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseLocaleAdd( universe_key as ID, locale as String ) as Boolean
// : adds a locale to the list of supported locales for this universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the locale does not meet constraints
//     => the locale is already in the list
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseLocaleRemove( universe_key as ID, locale as String ) as Boolean
// : removes a locale from the list of supported locales for this universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the locale does not meet constraints
//     => the locale not in the list
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseLocaleList( universe_key as ID, locales_out references List of String ) as Boolean
// : returns the list of supported locales for this universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseBaseLocaleSet( universe_key as ID, new_base_locale as String ) as Boolean
// : sets the base locale for this universe.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the locale does not meet constraints
//     => the locale is not in the list of supported locales
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseTableList( universe_key as ID, table_count_out references Integer, table_keys_out references List of ID, table_names_out references List of String, table_range_lows_out references List of Integer, table_range_highs_out references List of Integer, table_filenames_out references List of String ) as Boolean
// : retrieves the declarations of all of the string tables defined in the specified universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseRuntimeTableList( universe_key as ID, runtime_table_count_out references Integer, runtime_table_keys_out references List of ID, runtime_table_names_out references List of String, runtime_table_range_lows_out references List of Integer, runtime_table_range_highs_out references List of Integer ) as Boolean
// : retrieves the declarations of all of the runtime string tables defined in the specified universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseRuntimeTableFilesList( universe_key as ID, runtime_table_key as ID, locale_to_rt_filename_map as LookupList indexed by String of String) as Boolean
// : retrieves the locale-to-filename map from the specified runtime string table defined in the specified universe
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
 
external function Loc_UniverseDescribe( universe_key as ID, name_out references String, filename_out references String, runtime_filename_out references String, range_low references Integer, range_high references Integer, base_locale_out references String, locale_count_out references Integer, table_count_out references Integer, runtime_table_count_out references Integer ) as Boolean
// : returns the description for this universe.  The use of LOC_UniverseTableList, Loc_UniverseRuntimeTableList,
//   and LOC_UniverseLocaleList is used to return the detail information about tables and locales.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseTableCreate( universe_key as ID, name as String, filename as String, range_low as Integer, range_high as Integer, table_key_out references ID) as Boolean
// : Creates the new table in the specified universe.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the requested range is outside the bounds of the universe's range
//     => the requested range overlaps an existing table's range
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseTableRemove( universe_key as ID, table_key as ID ) as Boolean
// : removes a table from the universe.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the specified table is loaded
//     => the specified table is loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseRuntimeTableCreate( universe_key as ID, runtime_name as String, runtime_filename_for_base_locale as String, runtime_range_low as Integer, runtime_range_high as Integer, runtime_table_key_out references ID ) as Boolean
// : Creates the new runtime table in the specified universe.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//     => the requested range is outside the bounds of the universe's range
//     => the requested range overlaps an existing runtime table's range
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_UniverseRuntimeTableRemove( universe_key as ID, runtime_table_key as ID ) as Boolean
// : removes a runtime table from the universe.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe is not loaded
//     => the specified universe has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_RuntimeTableNameSet( runtime_table_key as ID, new_name as String ) as Boolean
// : sets the name of the specified runtime table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_RuntimeTableRangeSet( runtime_table_key as ID, new_range_low as Integer, new_range_high as Integer ) as Boolean
// : sets (changes) the range of the specified runtime table's string numbers
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified runtime table does not exist
//     => the new range is invalid
//     => the requested range is outside the bounds of the universe's range
//     => the requested range overlaps an existing runtime table's range
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_RuntimeTableFilenameForLocaleSet( runtime_table_key as ID, locale as String, new_filename as String ) as Boolean
// : sets the filename of the specified locale's runtime table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the locale is not in the list of supported locales for the development table
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_RuntimeTableDescribe( runtime_table_key as ID, name references String, locales_filename_map_out references LookupList indexed by String of String, range_low_out as Integer, range_high_out as Integer ) as Boolean
// : retrieves the definition of the specified runtime table.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified runtime table does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableLoadAsync( table_key as ID ) as Boolean  
// : begins loading the specified table.
//
// returns TRUE, upon beginning the loading process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist.
//     => the table has not yet completed loading.
//     => the repository file is not available
//     => the repository file is malformed
//     => the repository file is inconsistent with the table's declaration in the universe
//   Loc_SingleFileCallback(...)
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableUnload( table_key as ID ) as Boolean
// : causes the specified table to be unloaded from memory
//
// returns TRUE, upon the completion of the unloading process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => unsaved data exists in the table 
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TablePurgeWithoutSaving( table_key as ID ) as Boolean
// : causes a table to be unloaded from memory without checking for dirtiness
//
// returns TRUE, upon the completion of the purging process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableSaveAsync( table_key as ID ) as Boolean  
// : causes the specified table to be saved from memory to disk
//
// returns TRUE, upon beginning the saving process
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => the repository file can not be saved
//   Loc_SingleFileCallback(...)
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableNameSet( table_key as ID, new_name as String ) as Boolean
// : sets the name of the specified table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableFilenameSet( table_key as ID, new_filename as String ) as Boolean
// : sets the filename of the specified table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableRangeSet( table_key as ID, new_range_low as Integer, new_range_high as Integer ) as Boolean
// : sets (changes) the range of the specified table's string numbers
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => the new range is invalid
//     => the new range overlaps any existing range
//     => the new range would cause removal of already defined strings from the table
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableMetaGet( table_key as ID, meta_key_value_map_out references LookupList indexed by String of String ) as Boolean
// : retrieves the current meta-data settings
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableMetaSet( table_key as ID, meta_key_value_map as LookupList indexed by String of String ) as Boolean
// : establishes the current meta-data settings, replacing any former settings
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableLocaleAdd( table_key as ID, locale_to_add as String ) as Boolean
// : adds a locale to the list of locales for this table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => the locale does not meet constraints
//     => the locale is already in the list
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableLocaleRemove( table_key as ID, locale_to_remove as String ) as Boolean
// : removes a locale from the list of locales for this table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//     => the locale does not meet constraints
//     => the locale not in the list
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableLocaleList( table_key as ID, locales_out references List of String ) as Boolean
// : returns the list of locales for this table
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableDescribe( table_key as ID, name_out references String, filename_out references String, range_low_out references Integer, range_high_out references Integer ) as Boolean
// : retrieves the definition of the specified table.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_TableStringList( table_key as ID, strings_out references List of Integer ) as Boolean
// : retrieves the list of string numbers present in the specified table.
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified table does not exist
//     => the specified table is not loaded
//     => the specified table has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
// Retrieves the lowest unassigned localized string id within a table
external function Loc_TableGetLowestUnusedLocalizedStringID( table_key as ID, lowest_available_localized_string_id references Integer ) as Boolean
// returns TRUE, if it succeeded
// returns FALSE, if all localized string ids within a table's range are in use
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
 
// Determine if a specified localization string id is in use within a table
external function Loc_TableIsLocalizedStringIDInUse( table_key as ID, localized_string_id as Integer ) as Boolean
// returns TRUE, if localized string id is in use within the specified table
// returns FALSE, if id is not in use
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
// causes SCRIPT ERRORS if localized_string_id is out of range for the specified table
 
external function Loc_StringCreate( string_num as Integer ) as Boolean
// : creates the specified string number.
//   Its initial value for context is a zero-length strings, and no locale translations exist.
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number already exists
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_StringRemove( string_num as Integer ) as Boolean
// : removes the specified string number.
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_StringGet( string_num as Integer, context_out references String, locale_value_map_out references LookupList indexed by String of String ) as Boolean
// : retrieves the context and locale/translated values map for the specified string number
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
external function Loc_StringContextGet( string_num as Integer, context references String ) as Boolean
// : retrieves the context for the specified string number
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_StringContextSet( string_num as Integer, new_context as String ) as Boolean
// : sets (changes) the specified string number's context value.
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
external function Loc_StringValueForLocaleGet( string_num as Integer, locale as String, value_out references String ) as Boolean
// : retrieves the requested locale's translated value for the specified string number
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//     => the locale is not in the supported list of locales for the configuration
//     => the locale is not in the supported list of locales for the universe
//     => the locale does not meet constraints
//     => the specified translation does not exist
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_StringValueForLocaleSet( string_num as Integer, locale as String, new_value as String ) as Boolean
// : sets (changes) the requested locale's translated value for the specified string number
// 
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified string is not mapped into any loaded universe
//     => the specified string is not mapped into any loaded table
//     => the specified string is not mapped into any runtime table
//     => the specified string number does not exist
//     => the locale is not in the supported list of locales for the configuration
//     => the locale is not in the supported list of locales for the universe
//     => the locale does not meet constraints
//     => the specified translation does not exist
//     => any constraint is violated
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_FindStringIDs ( pcre_regular_expression as String, range_low as Integer, range_high as Integer, id_list_operation as String, string_ids references List of Integer ) as Boolean
// : Searches currently-loaded strings within the user-specified range for matches to the user-specified regular expression. 
//   Matches are added or removed from the user-specified string ID list in accordance with the user-specified string ID list operation.
//
//   pcre_regular_expression is a Perl regular expression.
//
//   range (range_low, range_high) restricts the attempts to match to string_ids in the specified range (inclusive).  Range 0 0 causes the engine to search all
//       strings currently in memory.  If a range is specified and intersection (id_list_operation) is specified, it only checks the ids passed in the
//       string_ids list that are within the specified range it does not check the entire range.
//
//   id_list_operation tells the engine how to handle the string_ids list.  It must be the following values:
//       replace - list is cleared out prior to the addition of matching string_ids
//       union - list contains the union of the string_ids passed in and string_ids matching new expression
//       intersection - list contains the intersection of string_ids (e.g. only those string_ids passed in that also match the new expression)
//       empty string "" - same as replace
//
//
// returns TRUE, upon success (finding no matches for a particular expression is still considered to be successfully completed if no errors occurred)
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => specified string ids are not in memory (if intersection is specified)
//     => the configuration has not yet completed loading
//     => no tables are loaded to search
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully or if invalid id_list_operation specified
//
 
external function Loc_StringFindByNumber ( string_number as Integer, universe_key_out references ID, table_key_out references ID, runtime_table_key_out references ID ) as Boolean
// : retrieves the known universe / table / runtime table positions of the requested string number
//   returns values of '0' (NONE) if unknown
//
// returns TRUE, upon success
// returns FALSE, if an error occurs
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_GenerateRuntimeConfigurationAsync() as Boolean  
// : saves to the repository the runtime configuration file
//
// returns FALSE, if an error occurs
// returns TRUE, after the generation has begun
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => an error occurs writing to the repository
//   Loc_SingleFileCallback(...)
//     => when generation and writing has succeeded
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
 
external function Loc_GenerateRuntimeUniverseAsync( universe_key as ID ) as Boolean  
// : saves to the repository the runtime universe file
//
// returns FALSE, if an error occurs
// returns TRUE, after the generation has begun
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified universe does not exist
//     => an error occurs writing to the repository
//   Loc_SingleFileCallback(...)
//     => when generation and writing has succeeded
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//
 
external function Loc_GenerateRuntimeTableAsync( runtime_table_key as ID ) as Boolean
// : saves to the repository the specified runtime string table file for all locales
//
// returns FALSE, if an error occurs
// returns TRUE, after the generation has begun
//
// causes callback events:
//   LOC_OnAPICallFailed( ... )
//     => no configuration is in memory
//     => the configuration has not yet completed loading
//     => the specified runtime table does not exist
//     => any needed development string table is not loaded, or has not finished loading
//     => any needed development string table has not finished loading
//     => an error occurs writing to the repository
//   Loc_SingleFileCallback(...)
//   Loc_MultiFileCallback(...)
//     => when generation and writing has succeeded
//
// causes SCRIPT ERROR if LOC_Startup has not been called successfully
//

DEV-Mode Callbacks

The Loc_OnAPICallFailed callback is called in response to synchronous errors or warnings.

• failure_severity indicates the type: "ERROR", "WARNING", or "TRANSIENT". An example of a "TRANSIENT" error is an attempt to access a file while it is still in the process of asynchronously loading.
• failiure_reason is a detailed error or warning message.
• failure_data is currently unused.
  

  method LOC_OnAPICallFailed( api_call as String, failure_severity as String, failure_reason as String, failure_data as LookupList indexed by String of String )

  
  When an external function triggers the upload or download of a single repository file, the Loc_SingleFileCallback callback is invoked to report the success or failure of the asynhcronous repository access.

  external_function is the name of the external function which triggered the repository access (for example: "Loc_TableSaveAsync").

  file_name is the file's repository pathname.

  ok indicates whether the upload/download completed successfully.

  if ok = false:

  • failure_severity indicates the type: "ERROR", "WARNING", or "TRANSIENT". An example of a "TRANSIENT" error is an attempt to access a file while it is still in the process of asynchronously loading.
  • failiure_reason is a detailed error or warning message.

  method LOC_SingleFileCallback( external_function as String, file_key as ID, file_name as String, ok as Boolean, failure_severity as String, failure_reason as String )

  
  

  When an external function triggers the upload or download of multiple repository files, the Loc_MultiFileCallback callback is invoked to report the success or failure of the asynhcronous repository accesses.

  external_function is the name of the external function which triggered the repository access (for example: "Loc_SaveAllAsync").

  total_file_count is the total number of files for which asynchronous upload or download was attempted.
  

  failed_file_count is the total number of files for which asynchronous upload or download failed.

  keys is a list of the file keys for all files for which asynchronous upload or download was attempted. It contains "total_file_count" keys.

  file_names is a lookup list (indexed by file key) of repository pathnames for all files for which asynchronous upload or download was attempted. 
  

  failed_file_severity is a lookup list (indexed by file key) of failure_severity strings for all files for which asynchronous upload or download failed. The failure_severity strings are the same as defined for the Loc_OnAPICallFailed and Loc_SingleFileCallback callbacks.

  failed_file_reason is a lookup list (indexed by file key) of detailed error messages for all files for which asynchronous upload or download failed.
  

  method LOC_MultiFileCallback( external_function as String, 
  			      total_file_count as Integer, 
  			      failed_file_count as Integer, 
  			      keys as List of ID, 
  			      filenames as LookupList indexed by ID of String, 
  			      failed_file_severity as LookupList indexed by ID of String, 
  			      failed_file_reason as LookupList indexed by ID of String )

  RT-Mode Localization

  RT-Mode External Functions

  // ----------------------------------------------------------------------------------------------
  // LOC_RTStartup initializes the run-time localization system.
  //
  // Arguments:
  // "callback_node" specifies the HSL node upon which callbacks for most RT-mode external functions
  // are to be delivered.
  // The single exception is the "got-localized-string" callback (LOC_RTGotLocalizedString).
  // It is invoked on the callback node specified when asynchronous string retrieval is
  // requested via the LOC_RTGetLocalizedString() external function.
  //
  // Throws ScriptError exception if localization has not already been initialized and:
  // - callback node is invalid, or
  // - callback node does not implement one or more required callbacks (NOT IMPLEMENTED YET), or
  // - initialization fails for any other reason.
  //
  // Never calls callback scripts.
  //
  // Returns:
  // - True if localization was successfully initialized.
  // - False if localization was already initialized.
  // ----------------------------------------------------------------------------------------------
  

  external function LOC_RTStartup( callback_node as NodeRef ) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTLoadConfiguration asynchronously downloads the specified runtime localization configuration file
  // from the repository. The config file is a singleton object through which all other localization objects
  // are referenced. If a config file is currently downloaded, it must be explicitly deleted using
  // LOC_RTUnloadConfigurationFile() before a new config file can be downloaded.
  //
  // Arguments:
  // "filename" is the repository path of the runtime configuration file to be downloaded.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized.
  //
  // Calls callback scripts:
  // - LOC_RTOnFileLoaded() if the asynchronous download completes successfully.
  // - LOC_RTOnError() upon any error other than localization-not-initialized.
  //
  // Returns:
  // - True upon successful initialization of asynchronous download.
  // - False upon config-file-already-downloaded or any other synchronous error besides
  // localization-not-initialized.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTLoadConfiguration( filename as String ) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTUnloadConfiguration deletes the singleton runtime localization configuration file and all its
  // dependent universe files and string table files from memory. Since only those universe files referenced
  // by the singleton config file can be loaded, and only those string table files referenced by a loaded
  // universe file can be loaded, LOC_RTUnloadConfiguration is in effect a delete-all operation. Any pending
  // asynchronous file downloads or string retrievals are effectively canceled.
  //
  // Arguments:
  // none
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized.
  //
  // Calls callback scripts:
  // - LOC_RTOnError() upon any error other than localization-not-initialized.
  //
  // Returns:
  // - True upon successful unloading of all runtime localization files.
  // - False upon any error other than localization-not-initialized.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTUnloadConfiguration() as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTDescribeConfiguration returns the properties of the currently downloaded runtime configuration file.
  //
  // Arguments:
  // "locales_out" is a list of the config file locales.
  // "universe_count_out" is the number of universe files belonging to the config file.
  // "universe_keys_out" is the list of key IDs of all universe files belonging to the config file.
  // "universe_filenames_out" is a lookup list of the repository pathnames of all universe files
  // belonging to the config file, indexed by key ID.
  // "universe_range_lows_out" is a lookup list of the minimum string ID of all universe files
  // belonging to the config file, indexed by key ID.
  // "universe_range_highs_out" is a lookup list of the maximum string ID of all universe files
  // belonging to the config file, indexed by key ID.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no configuration file has been loaded.
  //
  // Calls callback scripts:
  // - LOC_RTOnError() upon any error other than localization-not-initialized or config-not-loaded.
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized or config-not-loaded.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTDescribeConfiguration (locales_out references List of String,
  universe_count_out references Integer,
  universe_keys_out references List of ID,
  universe_filenames_out references LookupList indexed by ID of String,
  universe_range_lows_out references LookupList indexed by ID of Integer,
  universe_range_highs_out references LookupList indexed by ID of Integer) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTLoadUniverse asynchronously downloads the specified runtime localization universe file from the
  // repository.
  //
  // Arguments:
  // "universe_key" is the key ID of the runtime universe file to be downloaded. It must be a universe
  // file key that is referenced in the currently-downloaded configuration file.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no runtime configuration file is loaded, or
  // - the specified universe key is not in the currently-loaded runtime configuration file.
  //
  // Calls callback scripts:
  // - LOC_RTOnFileLoaded() if the asynchronous download completes successfully.
  // - LOC_RTOnError() upon any error other than localization-not-initialized, no-config-file, or
  // invalid-universe-key.
  //
  // Returns:
  // - True upon successful initialization of asynchronous download.
  // - False upon universe-file-already-downloaded or any other synchronous error besides
  // localization-not-initialized, no-config-file, or invalid-universe-key.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTLoadUniverse( universe_key as ID ) as Boolean

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTUnloadUniverse deletes the specified localization universe file and all its dependent string table
  // files from memory. Any affected pending asynchronous file downloads or string retrievals are effectively
  // canceled.
  //
  // Arguments:
  // "universe_key" is the key ID of the runtime configuration file to be unloaded. It must be a universe
  // file key that is referenced in the currently-downloaded configuration file.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no runtime configuration file is loaded, or
  // - the specified universe key is not in the currently-loaded runtime configuration file.
  //
  // Calls callback scripts:
  // - LOC_RTOnError() upon any error other than localization-not-initialized, no-config-file, or
  // invalid-universe-key.
  //
  // Returns:
  // - True upon successful unloading of the runtime universe file and all its child string table files.
  // - False upon universe-file-not-downloaded or any other synchronous error besides
  // localization-not-initialized, no-config-file, or invalid-universe-key.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTUnloadUniverse( universe_key as ID ) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------------
  // LOC_RTDescribeUniverse returns the properties of the specified downloaded runtime universe file.
  //
  // Runtime universe files manage multiple "runtime string tables". A runtime string table provides translations
  // for the runtime universe locales across a unique range of string IDs. Runtime string tables manage a different
  // runtime string table file for each runtime universe locale.
  //
  // Arguments:
  // - "universe_key_in" specifies the universe file which is to be described.
  // - "base_locale_out" is the locale in which localized strings are returned should a translation be unavailable
  // for the "current locale" (managed via LOC_RT<Get|Set>CurrentLocale()).
  // - "universe_locales_out" is a list of locales for which the universe file provides translations.
  // - "table_count_out" is the number of runtime string tables belonging to the specified universe file.
  // - "table_keys_out" is the list of key IDs of all runtime string tables belonging to the specified universe file.
  // - "table_range_lows_out" is a lookup list of the minimum string IDs of all runtime string tables belonging to
  // the specified universe file, indexed by runtime string table key ID.
  // - "table_range_highs_out" is a lookup list of the maximum string IDs of all runtime string tables belonging to
  // the specified universe file, indexed by string table key ID.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no configuration file has been loaded, or
  // - the specified universe key is not in the currently-loaded runtime configuration file, or
  // - the specified universe file has not been loaded.
  //
  // Calls callback scripts:
  // - none
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized, config-not-loaded, invalid-universe-key, or
  // universe-not-loaded.
  // ----------------------------------------------------------------------------------------------------------------
  external function LOC_RTDescribeUniverse (universe_key_in as ID,
  base_locale_out references String,
  universe_locales_out references List of String,
  table_count_out references Integer ,
  table_keys_out references List of ID,
  table_range_lows_out references LookupList indexed by ID of Integer,
  table_range_highs_out references LookupList indexed by ID of Integer ) as Boolean

  
  

  // -------------------------------------------------------------------------------------------------------------
  // LOC_RTLoadStringTable asynchronously downloads the specified runtime string table from the repository.
  // A runtime string table references an indefinite number of runtime string table files.
  //
  // Arguments:
  // "string_table_key" is the key ID of the runtime string table to be downloaded. String table keys map
  // one-to-one to [runtime_table_#] sections in runtime universe files. string_table_key must be referenced
  // in a [runtime_table_#] section in a currently-downloaded universe file.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no runtime configuration file is loaded, or
  // - the specified string table key is not found in a currently-loaded runtime universe file.
  //
  // Calls callback scripts:
  // - LOC_RTOnFilesLoaded() when the asynchronous download of all runtime string table files completes,
  // regardless of whether all the downloads are successful or not.
  // - LOC_RTOnError() upon any synchronous error other than localization-not-initialized, no-config-file, or
  // invalid-string table-key.
  //
  // Returns:
  // - True upon successful initialization of all asynchronous downloads.
  // - False upon runtime-string-table-already-downloaded or any other synchronous error besides
  // localization-not-initialized, no-config-file, or invalid-string table-key.
  // -------------------------------------------------------------------------------------------------------------
  external function LOC_RTLoadStringTable (string_table_key as ID) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------
  // LOC_RTUnloadStringTable deletes all runtime string table files and all ancillary memory belonging to the
  // specified runtime string table from memory. Any affected pending asynchronous file downloads or string
  // retrievals are canceled.
  //
  // Arguments:
  // "string_table_key" is the key ID of the runtime string table to be unloaded. It must be a string table
  // key that is referenced in a currently-downloaded universe file.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no runtime configuration file is loaded, or
  // - no currently-loaded universe contains the specified string table.
  //
  // Calls callback scripts:
  // - LOC_RTOnError() upon any error other than localization-not-initialized, no-config-file, or
  // invalid-string-table-key.
  //
  // Returns:
  // - True upon successful unloading of the runtime string table and all its child string table files.
  // - False upon string-table-not-downloaded or any other synchronous error besides
  // localization-not-initialized, no-config-file, or invalid-string-table-key.
  // ----------------------------------------------------------------------------------------------------------
  external function LOC_RTUnloadStringTable (string_table_key as ID) as Boolean

  
  

  // --------------------------------------------------------------------------------------------------------------
  // LOC_RTGetLocalizedString asynchronously retrieves the localized string uniquely identified by the combination
  // of the specified string ID and the current locale (managed by LOC_RT<Get|Set>CurrentLocale()).
  //
  // A configuration file must be loaded before LOC_RTGetLocalizedString() can be called. But, once a configuration
  // file has been loaded, universe files and string tables will be dynamically loaded as required.
  //
  // Also, if the requested string is in a swapped-out string table file, the string table file is swapped back in
  // and other string table file(s) are swapped out if necessary to stay under the string table memory threshold.
  //
  // Arguments:
  // "string_id_in" (in combination with the current locale) specifies the string to be retrieved.
  // "async_string_request_id_in" uniquely identifies the asynchronous string request.
  // "callback_node_in" identifies the HSL node upon which callbacks for this string request are to be made.
  //
  // Because the current locale can be modified via LOC_RTSetCurrentLocale() at any time, the string ID in and of
  // itself is insufficient to uniquely map a translated string returned by the LOC_RTGotLocalizedString callback
  // script to a particular locale. However, the HSL scripter can use "async_string_request_id" to specify a unique
  // ID.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no runtime configuration file is loaded, or
  // - the specified string ID is invalid, or
  // - the specified callback node is invalid, or
  // - the asynchronous string request ID is not unique.
  //
  // Calls callback scripts:
  // - LOC_RTGotLocalizedString() upon successful retrieval of the string.
  // - LOC_RTOnError() upon any error other than localization-not-initialized, no-config-file,
  // invalid-callback-node, or invalid-async-string-request-id.
  //
  // Returns:
  // - If a swapped-out string table file must be reloaded, returns true upon successful initialization of the
  // asynchronous download.
  // - If swapping-in is not required, returns true after the LOC_RTGotLocalizedString callback has been called.
  // - False upon any other synchronous error besides localization-not-initialized, no-config-file,
  // invalid-string-id, invalid-callback-node, or invalid-async-string-request-id.
  // --------------------------------------------------------------------------------------------------------------
  external function LOC_RTGetLocalizedString (string_id_in as Integer, async_string_request_id_in as ID, callback_node_in as NodeRef) as Boolean

  
  

  // --------------------------------------------------------------------------------------------------------------
  // LOC_RTGetLocalizedStringSynchronously synchronously retrieves the localized string uniquely identified by the
  // combination of the specified string ID and the current locale (managed by LOC_RT<GET|Set>CurrentLocale()). If
  // the string is in a swapped-out string table file, LOC_RTGetLocalizedStringSynchronously() fails.
  //
  // Arguments:
  // "string_id_in" (in combination with the current locale) specifies the string to be retrieved.
  // "string_translation_out" is the localized string in UTF-16 format.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized.
  //
  // Calls callback scripts:
  // - none.
  //
  // Returns:
  // - True upon successful synchronous retrieval of the localized string.
  // - False upon any error other than localization-not-initialized. The error description is returned in the
  // string itself:
  // "INVALID STRING ID"
  // when the specified string ID is invalid (i.e., equal to zero)
  // "CONFIGURATION NOT LOADED":
  // when no configuration has been specified to be loaded
  // "CONFIGURATION NOT YET LOADED":
  // when the configuration has been specified to load, but has not yet finished loading
  // "OUT OF RANGE":
  // when the specified string ID is not within the valid ranges for the loaded configuration
  // "UNIVERSE NOT LOADED":
  // when the universe in which the string is located has not been requested to be loaded
  // "UNIVERSE NOT YET LOADED":
  // when the universe has been requested to be loaded, but has not yet finished loading
  // "TABLE NOT FOUND":
  // when the universe in which the string is located does not contain a table which contains
  // the string.
  // "TABLE NOT LOADED":
  // when the table in which the string is located has not been requested to be loaded
  // "TABLE NOT YET LOADED":
  // when the table has been requested to be loaded, but has not yet finished loading
  // "NOT FOUND":
  // when the string ID is within a valid range and the string table has been loaded,
  // but the string is not present within the table data
  //
  // --------------------------------------------------------------------------------------------------------------
  external function LOC_RTGetLocalizedStringSynchronously (string_id_in as Integer, localized_string_out references String) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------------
  // LOC_RTGetCurrentLocale returns the current locale.
  //
  // Arguments:
  // - "current_locale" is the returned current locale name.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no configuration file has been loaded.
  //
  // Calls callback scripts:
  // - LOC_OnRTUserError if LOC_RTSetCurrentLocale has not been called to set the current locale,
  // or upon any other errors besides localization-not-initialized or config-not-loaded.
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized or config-not-loaded.
  // ----------------------------------------------------------------------------------------------------------------
  external function LOC_RTGetCurrentLocale (current_locale_out references String) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------------
  // LOC_RTSetCurrentLocale sets the current locale. The current locale specifies the preferred language in which
  // localized strings are to be returned by the LOC_RTGetLocalizedString and LOC_RTGetLocalizedStringSynchronously
  // external functions. If a current locale has not been defined or if no translation is available for the current
  // locale, a translation for the base locale (as defined by the universe) is returned instead. If no translation
  // is available for the base locale, an error is reported.
  //
  // Arguments:
  // - "new_current_locale" is the name of the new current locale.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no configuration file has been loaded.
  //
  // Calls callback scripts:
  // - LOC_OnRTUserError upon errors other than localization-not-initialized or config-not-loaded.
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized or config-not-loaded.
  // ----------------------------------------------------------------------------------------------------------------
  external function LOC_RTSetCurrentLocale (current_locale_in as String) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------------
  // Operating systems usually have a "system locale" which specifies the default language used by non-Unicode
  // application's GUIs.
  //
  // LOC_RTGetOSLocale() returns the system locale.
  //
  // Arguments:
  // - "system_locale" is the returned system locale name.
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - the host operating system doesn't implement system locales.
  //
  // Calls callback scripts:
  // - Never.
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized or system-locale-not-implemented.
  // ----------------------------------------------------------------------------------------------------------------
  external function LOC_RTGetOSLocale (os_locale references String) as Boolean

  
  

  // ----------------------------------------------------------------------------------------------------------------
  // LOC_RTGetParameters returns the localization runtime parameters, which are loaded from the configuration
  // file's [runtime_parameters] section.
  //
  // Arguments:
  // - "parameters_out" is a string-to-string key-value lookup table specifying the current runtime parameters
  //
  // Throws ScriptError exception if:
  // - localization has not been initialized, or
  // - no configuration file has been loaded.
  //
  // Calls callback scripts:
  // - none
  //
  // Returns:
  // - True upon success.
  // - False upon any error other than localization-not-initialized or config-not-loaded.
  // ----------------------------------------------------------------------------------------------------------------
  external function LOC_RTGetParameters (parameters_out references LookupList indexed by String of String) as Boolean
  

  
  

  RT-Mode Callbacks

  // -------------------------------------------------------------------------------------------------------------------------------------------
  // LOC_OnRTLoadFile() is called when the asynchronous download of a configuration or universe file is
  // successfully completed.
  // -------------------------------------------------------------------------------------------------------------------------------------------

  method LOC_OnRTLoadFile( key as ID )
  

  // -------------------------------------------------------------------------------------------------------------------------------------------------------
  // LOC_OnRTLoadFileFailed() is called when the asynchronous download of a configuration or universe file fails.
  // -------------------------------------------------------------------------------------------------------------------------------------------------------

  method LOC_OnRTLoadFileFailed( key as ID, errmsg as String )
  

  
  

  // --------------------------------------------------------------------------------------------------------------------------------------------
  // The LOC_RTLoadStringTable() external function loads string table files for both the current locale
  // and the base locale, if possible.
  //
  // LOC_OnRTLoadStringTable() is called when the asynchronous downloads of all string table files are
  // successfully completed.
  // ---------------------------------------------------------------------------------------------------------------------------------------------
  

  method LOC_OnRTLoadStringTable( key as ID )
  

  // ---------------------------------------------------------------------------------------------------------------------------------------------------
  // LOC_OnRTLoadStringTableFailed() is called when one or both asynchronous string table file downloads
  // started by the LOC_RTLoadStringTable() external function fail.
  //
  // SPECIAL NOTE FOR HSL SCRIPT AUTHORS:
  //    Receipt of a LOC_OnRTLoadStringTableFailed callback does not necessarily mean that the localized
  //    strings belonging to the string table cannot be retrieved by the LOC_RTGetLocalizedString() or
  //    LOC_RTGetLocalizedStringSynchronously() external functions. If the current-locale string table
  //    file downloads successfully and the base-locale string table file download fails, the string
  //    retrieval external functions attempt to get the string from the current-locale string table file,
  //    and vice versa.
  //
  // *_locale_load_status is one of:
  //    - "LOADED" if the asynchronous download of the string table file for the specified locale succeeded.
  //    - "LOAD FAILED" if the asynchronous download of the string table file for the specified locale failed.
  //    - "NO FILE" if the [runtime_table_#] section referenced by hs_string_table_key does not contain a
  //       string table file for the specified locale.
  //    - "UNDEFINED" if the current locale has not yet been defined via the LOC_RTSetCurrentLocale() external
  //       function (this, of course, applies only to hs_current_locale_load_status).
  //
  // If *_locale_load_status is "LOAD FAILED",  *_locale_error_description provides detailed error info.
  // Otherwise, it is an empty string.
  // ---------------------------------------------------------------------------------------------------------------------------------------------------
  

  method LOC_OnRTLoadStringTableFailed( key as ID,

                                                                                  base_locale_name as String, base_locale_load_status as String, base_locale_errmsg as String,

                                                                                  current_locale_name as String, current_locale_load_status as String, current_locale_errmsg as String )
  

  
  

  // -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  // LOC_OnRTGetLocalizedString() is called when an asynchronous localized string retrieval is successfully completed.
  //
  // String IDs in and of themselves do not uniquely identify a localized string. A locale is also required. The "current
  // locale" (managed by the LOC_RT<Get/Set>CurrentLocale() external functions) at the time of the LOC_RTGetLocalizedString()
  // request is used to determine which translation to return.
  //
  // Because LOC_RTGetLocalizedString() is asynchronous, you could start asynchronous retrieval of string X, modify the
  // current locale, and then start another retrieval of string X before the first one completes. If you depended solely on
  // the string ID to identify the asynchronously returned string, you might get the string in Inuit when you were expecting
  // to get it in Tagalog, or whatever.
  //
  // In other words, string IDs do not provide an unambiguous mapping from an asynchronous retrieval request to a returned
  // string. The "hs_async_request_id" (which is sent by HSL with the LOC_RTGetLocalizedString() request) must be used instead.
  // It is the responsibility of the HSL script developer to ensure that asynchronous request IDs are unique.
  // -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  

  method LOC_OnRTGetLocalizedString( async_request_id as ID, localized_string as String )

  
  

  // ------------------------------------------------------------------------------------------------------------------------------------------
  // LOC_OnRTGetLocalizedStringFailed() is called when an asynchronous localized string retrieval fails.
  // ------------------------------------------------------------------------------------------------------------------------------------------

  method LOC_OnRTGetLocalizedStringFailed( async_request_id as ID, errmsg as String )
  
  

  // ------------------------------------------------------------------------------------------------------------------------
  // In general, HeroEngine best practice is to throw a ScriptError upon detection of an error
  // that is most likely attributable to a C++ or HSL logic error, and to provide user-friendly
  // error messages when a probable user error is detected.
  //
  // LOC_OnRTError() is a general-purpose callback for user-friendly error reporting.
  

  // ------------------------------------------------------------------------------------------------------------------------

  method LOC_OnRTError( external_function_name as String, errmsg as String )

  Retrieved from "http://hewiki.heroengine.com/wiki/Localization_External_Functions"
  Category: Localization

• Privacy policy
• About HEWIKI
• Disclaimers

• Copyright (c) 2006-2013 Idea Fabrik Plc. All Rights Reserved.
• HeroCloud is a registered trademark of IdeaFabrik Plc, all rights reserved
• HeroEngine is a registered trademark of IdeaFabrik Plc, all rights reserved

•