HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Developer's Guide: Language: code and content

» Return to Contents



We define a difference between 'code' (the translation of the site usage process, in language string form) and 'content' (the translation of the content that is added to the site).

Some language guidelines:
  • Don't split up phrases, use {1} {2} and {3} to insert variables instead. There is no guarantee that different languages assemble together in the same way. It is also a lot cleaner like this. HTML is allowed, where supported and where the string'll solely be used in HTML
  • Don't translate technical terms. These include: cookie, localhost, comcode, CEDI, ocPortal, chmod, FTP, SQL, PHP, XHTML, HTML, SMTP, GD, SUEXEC, Gzipped, POP3
  • charset is a special entry, and is the character set of the language
  • Also when needed, add comments to define context
  • Try to reuse strings as much as possible. Don't add new strings unless it is really needed, as they need to be translated into potentially dozens of languages
  • Good grammar is important. We Don't Capitalise Like This. We do it nicely like this. Consistency! Sometimes multi-word proper nouns are given hyphens, sometimes concatenation is used, sometimes CamelCase is used, sometimes abbreviation is used by just using the first letters placed together as capitals, and sometimes each word is given in capitals - this inconsistency is ingrained in English, but for any single term, reference it in a uniform way
  • Plurality-Wrong: Apple's. Plurality-Right: Apples. Possession-Wrong: Pauls. Possession-Right: Paul's. Compaction-Wrong: Its. Compaction-Right: It's. S-Ending-Pocession-Wrong: Chris' (unless there is more than one Chris). S-Ending-Pocession-Right: Chris's.
  • Phrases should be phrased as generally as possible… i.e. without using context or tense; this allows reuse
  • If phrases are not general, then put them in a language file that can be individually included by a module
  • Language strings must not include html symbols like ' " < > and &. These should be turned into HTML entities, such as & or <

sources/lang.php

Global_functions_lang.php

Function summary

void init__lang ()
?mixed do_lang (ID_TEXT codename, ?mixed token1, ?mixed token2, ?mixed token3, ?LANGUAGE_NAME lang, boolean require_result)
void open_page_cache_file ()
LANGUAGE_NAME fallback_lang ()
LANGUAGE_NAME user_lang ()
?LANGUAGE_NAME get_lang_browser ()
boolean does_lang_exist (LANGUAGE_NAME lang)
LANGUAGE_NAME get_site_default_lang ()
?LANGUAGE_NAME get_lang_forum_user (MEMBER member)
LANGUAGE_NAME get_lang (?MEMBER member)
void require_lang (ID_TEXT codename, ?LANGUAGE_NAME lang, ?string type, boolean ignore_errors)
void require_all_lang (?LANGUAGE_NAME lang, boolean only_if_for_lang)
integer lang_code_to_default_content (ID_TEXT code, boolean comcode, integer level)
void require_all_open_lang_files (?LANGUAGE_NAME lang)
tempcode urlise_lang (string string, mixed url, string title, boolean new_window)
tempcode protect_from_escaping (mixed in)
?mixed _do_lang (ID_TEXT codename, ?mixed token1, ?mixed token2, ?mixed token3, ?LANGUAGE_NAME lang, boolean require_result)
array find_all_langs (boolean even_empty_langs)
tempcode nice_get_langs (?LANGUAGE_NAME select_lang, boolean show_unset)
integer insert_lang_comcode (string text, integer level, ?object connection, boolean insert_as_admin, ?string pass_id, integer wrap_pos, boolean preparse_mode, boolean save_as_volatile)
integer insert_lang (string text, integer level, ?object connection, boolean comcode, ?integer id, ?LANGUAGE_NAME lang, boolean insert_as_admin, ?string pass_id, ?string text2, integer wrap_pos, boolean preparse_mode, boolean save_as_volatile)
integer lang_remap_comcode (integer id, string text, ?object connection, ?string pass_id, ?MEMBER source_member, boolean as_admin)
integer lang_remap (integer id, string text, ?object connection, boolean comcode, ?string pass_id, ?MEMBER source_member, boolean as_admin, boolean backup_string)
void delete_lang (integer id, ?object connection)
?tempcode get_translated_tempcode (integer entry, ?object connection, ?LANGUAGE_NAME lang, boolean force, boolean as_admin, boolean clear_away_from_cache)
?string get_translated_text (integer entry, ?object connection, ?LANGUAGE_NAME lang, boolean force)
tempcode comcode_lang_string (ID_TEXT lang_code)
mixed choose_language (tempcode title, boolean tip, boolean allow_all_selection)

void init__lang()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

?mixed do_lang(ID_TEXT codename, ?mixed token1, ?mixed token2, ?mixed token3, ?LANGUAGE_NAME lang, boolean require_result)

Get the human-readable form of a language id, or a language entry from a language INI file.

Parameters…

Name codename
Description The language id
Type ID_TEXT

Name token1
Description The first token [string or tempcode] (replaces {1}) (NULL: none)
Default value
Type ?mixed

Name token2
Description The second token [string or tempcode] (replaces {2}) (NULL: none)
Default value
Type ?mixed

Name token3
Description The third token (replaces {3}). May be an array of [of string], to allow any number of additional args (NULL: none)
Default value
Type ?mixed

Name lang
Description The language to use (NULL: users language)
Default value
Type ?LANGUAGE_NAME

Name require_result
Description Whether to cause ocPortal to exit if the lookup does not succeed
Default value boolean-true
Type boolean

Returns…

Description The human-readable content (NULL: not found). String normally. Tempcode if tempcode parameters.
Type ?mixed

Return to the function index for this class Expand: View the source code to this function

void open_page_cache_file()

Open up our language cache file for appending.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

LANGUAGE_NAME fallback_lang()

This function is called when no other language works, and it will return the original default language - 'EN'. You may change this to another language, but this is not advised, as ocPortal is being shipped with the EN language complete and unabridged as standard - hence you cannot go wrong if you leave it as EN.In theory, this is the only hook to English that there is.

Parameters…

Returns…

Description The fallback language
Type LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

LANGUAGE_NAME user_lang()

Get the user's currently selected language.

Parameters…

Returns…

Description The user's current language
Type LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

?LANGUAGE_NAME get_lang_browser()

Get the closest fit language code to what the browser is requesting.

Parameters…

Returns…

Description The closest-fit language to what the browser wants (NULL: browser doesn't ask)
Type ?LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

boolean does_lang_exist(LANGUAGE_NAME lang)

Find whether the specified language exists.

Parameters…

Name lang
Description The language
Type LANGUAGE_NAME

Returns…

Description Whether the language exists
Type boolean

Return to the function index for this class Expand: View the source code to this function

LANGUAGE_NAME get_site_default_lang()

Get the site's default language, with support for URL overrides.

Parameters…

Returns…

Description The site's default language
Type LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

?LANGUAGE_NAME get_lang_forum_user(MEMBER member)

Get what language the given member uses. The language is sent through a mapping to ensure it is in the right format, or dumped if it will not map.

Parameters…

Name member
Description The member id
Type MEMBER

Returns…

Description The language used by the member (NULL: the language will not map)
Type ?LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

LANGUAGE_NAME get_lang(?MEMBER member)

Get the current language.First it tries to get the GET or POST language values, then it tries the user's language, then site default, then it resorts to EN.

Parameters…

Name member
Description The member id (NULL: site default language, although better just to call get_site_default_lang directly)
Default value
Type ?MEMBER

Returns…

Description The current language
Type LANGUAGE_NAME

Return to the function index for this class Expand: View the source code to this function

void require_lang(ID_TEXT codename, ?LANGUAGE_NAME lang, ?string type, boolean ignore_errors)

Includes a language file for use in the script.If $type is not null, then this specifies whether to use 'lang_custom' or 'custom' (otherwise, normal priorities occur).

Parameters…

Name codename
Description The language file name
Type ID_TEXT

Name lang
Description The language (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

Name type
Description The language type (lang_custom, or custom) (NULL: normal priorities are used)
Default value
Type ?string
Values restricted to lang_custom custom

Name ignore_errors
Description Whether to just return if there was a loading error
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

void require_all_lang(?LANGUAGE_NAME lang, boolean only_if_for_lang)

Include all the language files for use in the script.NOTE: This may reduce performance, so you should only use it if you really have to.

Parameters…

Name lang
Description The language to include files from (NULL: use current users language).
Default value
Type ?LANGUAGE_NAME

Name only_if_for_lang
Description Only load it up if it is specifically defined for our language.
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

integer lang_code_to_default_content(ID_TEXT code, boolean comcode, integer level)

Convert the specified language codename to the default content, and return the language key.

Parameters…

Name code
Description The language codename
Type ID_TEXT

Name comcode
Description Whether the given codes value is to be parsed as comcode
Default value boolean-false
Type boolean

Name level
Description The level of importance this language string holds
Default value 2
Type integer

Returns…

Description The language ID
Type integer

Return to the function index for this class Expand: View the source code to this function

void require_all_open_lang_files(?LANGUAGE_NAME lang)

Require all the open language files. This doesn't hurt performance a lot.

Parameters…

Name lang
Description The language to require open files from (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

(No return value)


Return to the function index for this class Expand: View the source code to this function

tempcode urlise_lang(string string, mixed url, string title, boolean new_window)

URL'ise specially encoded text-acceptance language strings.

Parameters…

Name string
Description The language string
Type string

Name url
Description The URL (either tempcode or string)
Type mixed

Name title
Description The title of the hyperlink
Default value
Type string

Name new_window
Description Whether to use a new window
Default value boolean-false
Type boolean

Returns…

Description The encoded version
Type tempcode

Return to the function index for this class Expand: View the source code to this function

tempcode protect_from_escaping(mixed in)

Stop some text being escapable by the Tempcode layer.

Parameters…

Name in
Description Text
Type mixed

Returns…

Description Text that can't be escaped
Type tempcode

Return to the function index for this class Expand: View the source code to this function

?mixed _do_lang(ID_TEXT codename, ?mixed token1, ?mixed token2, ?mixed token3, ?LANGUAGE_NAME lang, boolean require_result)

Get the human-readable form of a language id, or a language entry from a language INI file.

Parameters…

Name codename
Description The language id
Type ID_TEXT

Name token1
Description The first token [string or tempcode] (replaces {1}) (NULL: none)
Default value
Type ?mixed

Name token2
Description The second token [string or tempcode] (replaces {2}) (NULL: none)
Default value
Type ?mixed

Name token3
Description The third token (replaces {3}). May be an array of [of string], to allow any number of additional args (NULL: none)
Default value
Type ?mixed

Name lang
Description The language to use (NULL: users language)
Default value
Type ?LANGUAGE_NAME

Name require_result
Description Whether to cause ocPortal to exit if the lookup does not succeed
Default value boolean-true
Type boolean

Returns…

Description The human-readable content (NULL: not found). String normally. Tempcode if tempcode parameters.
Type ?mixed

Return to the function index for this class Expand: View the source code to this function

array find_all_langs(boolean even_empty_langs)

Get an array of all the installed languages that can be found in root/lang/ and root/lang_custom/

Parameters…

Name even_empty_langs
Description Whether to even find empty languages
Default value boolean-false
Type boolean

Returns…

Description The installed languages (map, lang=>type)
Type array

Return to the function index for this class Expand: View the source code to this function

tempcode nice_get_langs(?LANGUAGE_NAME select_lang, boolean show_unset)

Get a nice formatted XHTML listed language selector.

Parameters…

Name select_lang
Description The language to have selected by default (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

Name show_unset
Description Whether to show languages that have no language details currently defined for them
Default value boolean-false
Type boolean

Returns…

Description The language selector
Type tempcode

Return to the function index for this class Expand: View the source code to this function

integer insert_lang_comcode(string text, integer level, ?object connection, boolean insert_as_admin, ?string pass_id, integer wrap_pos, boolean preparse_mode, boolean save_as_volatile)

Insert a comcode language entry into the translation table, and returns the id.

Parameters…

Name text
Description The text
Type string

Name level
Description The level of importance this language string holds
Type integer
Values restricted to 1 2 3 4

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name insert_as_admin
Description Whether to insert it as an admin (any comcode parsing will be carried out with admin privileges)
Default value boolean-false
Type boolean

Name pass_id
Description The special identifier for this lang code on the page it will be displayed on; this is used to provide an explicit binding between languaged elements and greater templated areas (NULL: none)
Default value
Type ?string

Name wrap_pos
Description Comcode parser wrap position
Default value 60
Type integer

Name preparse_mode
Description Whether to generate a fatal error if there is invalid Comcode
Default value boolean-true
Type boolean

Name save_as_volatile
Description Whether we are saving as a 'volatile' file extension (used in the XML DB driver, to mark things as being non-syndicated to subversion)
Default value boolean-false
Type boolean

Returns…

Description The id of the newly added language entry
Type integer

Return to the function index for this class Expand: View the source code to this function

integer insert_lang(string text, integer level, ?object connection, boolean comcode, ?integer id, ?LANGUAGE_NAME lang, boolean insert_as_admin, ?string pass_id, ?string text2, integer wrap_pos, boolean preparse_mode, boolean save_as_volatile)

Insert a language entry into the translation table, and returns the id.

Parameters…

Name text
Description The text
Type string

Name level
Description The level of importance this language string holds
Type integer
Values restricted to 1 2 3 4

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name comcode
Description Whether it is to be parsed as comcode
Default value boolean-false
Type boolean

Name id
Description The id to use for the language entry (NULL: work out next available)
Default value
Type ?integer

Name lang
Description The language (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

Name insert_as_admin
Description Whether to insert it as an admin (any comcode parsing will be carried out with admin privileges)
Default value boolean-false
Type boolean

Name pass_id
Description The special identifier for this lang code on the page it will be displayed on; this is used to provide an explicit binding between languaged elements and greater templated areas (NULL: none)
Default value
Type ?string

Name text2
Description Assembled Tempcode portion (NULL: work it out)
Default value
Type ?string

Name wrap_pos
Description Comcode parser wrap position
Default value 60
Type integer

Name preparse_mode
Description Whether to generate a fatal error if there is invalid Comcode
Default value boolean-true
Type boolean

Name save_as_volatile
Description Whether we are saving as a 'volatile' file extension (used in the XML DB driver, to mark things as being non-syndicated to subversion)
Default value boolean-false
Type boolean

Returns…

Description The id of the newly added language entry
Type integer

Return to the function index for this class Expand: View the source code to this function

integer lang_remap_comcode(integer id, string text, ?object connection, ?string pass_id, ?MEMBER source_member, boolean as_admin)

Remap the specified comcode language id, and return the id again - the id isn't changed.

Parameters…

Name id
Description The language entries id
Type integer

Name text
Description The text to remap to
Type string

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name pass_id
Description The special identifier for this lang code on the page it will be displayed on; this is used to provide an explicit binding between languaged elements and greater templated areas (NULL: none)
Default value
Type ?string

Name source_member
Description The member performing the change (NULL: current member)
Default value
Type ?MEMBER

Name as_admin
Description Whether to generate Comcode as arbitrary admin
Default value boolean-false
Type boolean

Returns…

Description The language entries id
Type integer

Return to the function index for this class Expand: View the source code to this function

integer lang_remap(integer id, string text, ?object connection, boolean comcode, ?string pass_id, ?MEMBER source_member, boolean as_admin, boolean backup_string)

Remap the specified language id, and return the id again - the id isn't changed.

Parameters…

Name id
Description The language entries id
Type integer

Name text
Description The text to remap to
Type string

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name comcode
Description Whether it is to be parsed as comcode
Default value boolean-false
Type boolean

Name pass_id
Description The special identifier for this lang code on the page it will be displayed on; this is used to provide an explicit binding between languaged elements and greater templated areas (NULL: none)
Default value
Type ?string

Name source_member
Description The member performing the change (NULL: current member)
Default value
Type ?MEMBER

Name as_admin
Description Whether to generate Comcode as arbitrary admin
Default value boolean-false
Type boolean

Name backup_string
Description Whether to backup the language string before changing it
Default value boolean-false
Type boolean

Returns…

Description The language entries id
Type integer

Return to the function index for this class Expand: View the source code to this function

void delete_lang(integer id, ?object connection)

Delete the specified language entry from the translation table.

Parameters…

Name id
Description The id
Type integer

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

(No return value)


Return to the function index for this class Expand: View the source code to this function

?tempcode get_translated_tempcode(integer entry, ?object connection, ?LANGUAGE_NAME lang, boolean force, boolean as_admin, boolean clear_away_from_cache)

This function is an offshoot of get_translated_text, it instead returns parsed comcode that is linked to the specified language id.

Parameters…

Name entry
Description The id
Type integer

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name lang
Description The language (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

Name force
Description Whether to force it to the specified language
Default value boolean-false
Type boolean

Name as_admin
Description Whether to force as_admin, even if the lang string isn't stored against an admin (designed for comcode page cacheing)
Default value boolean-false
Type boolean

Name clear_away_from_cache
Description Whether to remove from the Tempcode cache when we're done, for performance reasons (normally don't bother with this, but some code knows it won't be needed again – esp Comcode cache layer – and saves RAM by removing it)
Default value boolean-false
Type boolean

Returns…

Description The parsed comcode (NULL: the text couldn't be looked up)
Type ?tempcode

Return to the function index for this class Expand: View the source code to this function

?string get_translated_text(integer entry, ?object connection, ?LANGUAGE_NAME lang, boolean force)

Try to return the human-readable version of the language id, passed in as $entry.

Parameters…

Name entry
Description The id
Type integer

Name connection
Description The database connection to use (NULL: standard site connection)
Default value
Type ?object

Name lang
Description The language (NULL: uses the current language)
Default value
Type ?LANGUAGE_NAME

Name force
Description Whether to force it to the specified language
Default value boolean-false
Type boolean

Returns…

Description The human-readable version (NULL: could not look up when $force was on)
Type ?string

Return to the function index for this class Expand: View the source code to this function

tempcode comcode_lang_string(ID_TEXT lang_code)

Convert a language string that is Comcode to tempcode, with potential cacheing in the db.

Parameters…

Name lang_code
Description The language string ID
Type ID_TEXT

Returns…

Description The parsed Comcode
Type tempcode

Return to the function index for this class Expand: View the source code to this function

mixed choose_language(tempcode title, boolean tip, boolean allow_all_selection)

UI to choose a language.

Parameters…

Name title
Description Title for the form
Type tempcode

Name tip
Description Whether to give a tip about edit order
Default value boolean-false
Type boolean

Name allow_all_selection
Description Whether to add an 'all' entry to the list
Default value boolean-false
Type boolean

Returns…

Description The UI (tempcode) or the language to use (string/LANGUAGE_NAME)
Type mixed

Return to the function index for this class Expand: View the source code to this function


All translateable attributes in ocPortal are given priorities. The scheme for these priorities at the time of writing is as follows…

1 (absolutely crucial and permanent/featured)
  • zones.header_text
  • cached_comcode_pages.string_index
  • catalogues.c_title
  • galleries.fullname
  • news.title
  • news.news
  • news.news_article
  • news_categories.nc_title
  • poll.question
  • poll.option1
  • poll.option2
  • poll.option3
  • poll.option4
  • poll.option5
  • ticket_types.ticket_type
  • f_custom_fields.cf_name

2 (pretty noticeable: titles, descriptions of very-important)
  • seo_meta.meta_keywords
  • seo_meta.meta_description
  • galleries.description
  • catalogues.c_description
  • iotd.caption
  • text.the_message
  • catalogue_categories.cc_title
  • banners.caption
  • download_categories.category
  • download_downloads.name
  • seedy_posts.the_message
  • seedy_pages.title
  • seedy_pages.description
  • download_categories.description
  • catalogue_fields.cf_name
  • catalogue_fields.cf_description
  • f_custom_fields.cf_description

3 (full body descriptions)
  • authors.description
  • authors.skills
  • catalogue_categories.cc_description
  • filedump.description
  • images.comments
  • download_downloads.description
  • download_downloads.comments
  • catalogue_entry_field_values_long_trans.cv_value
  • catalogue_entry_field_values_short_trans.cv_value
  • f_multi_moderations.mm_name

4 (for individual members, or very low level)
  • chargelog.reason
  • gifts.reason
  • f_posts.p_post
  • f_members.m_signature