Short hand proc that invokes the lang::message::lookup proc. Returns a localized text from the message catalog with the locale ad_conn locale if invoked within a request, or the system locale otherwise.

Example:

    set the_url [export_vars -base "[ad_conn package_url]view" { item_id }]
    set body [_ my-package.lt_To_view_this_item [list item_url $the_url]]

Parameters:

key (required)

Unique identifier for this message. Will be the same identifier for each locale. The key is on the format package_key.message_key

substitution_list (optional)

A list of values to substitute into the message on the form { name value name value ... }. This argument should only be given for certain messages that contain place holders (on the syntax %1:pretty_name%, %2:another_pretty_name% etc) for embedding variable values. If the message contains variables that should be interpolated and this argument is not provided then upvar will be used to fetch the variable values.

Returns:

A localized message

Authors:

Jeff Davis <davis@xarg.net>

Peter Marklund <peter@collaboraid.biz>

Christian Hvid <chvid@collaboraid.biz>

See Also:

• lang::message::lookup
• lang::message::format

Partial Call Graph (max 5 caller/called nodes):

Testcases:

group_localization, acs_subsite_group_type

Loads the entire message catalog from the database into the cache.

Switches:

-force (optional, boolean)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_catalog_import_export

Check a message for semantic and sanity correctness (usually called just before a message is registered). Throws an error when one of the checks fails.

Parameters:

locale (required)

package_key (required)

message_key (required)

message (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

lang_messages_correct

Deletes a message in a particular locale.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_message_register

The regexp pattern used to loop over variables embedded in message catalog texts.

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

12 November 2002

Partial Call Graph (max 5 caller/called nodes):

Testcases:

message__get_embedded_vars

Substitute all occurencies of %array_key% in the given localized message with the value from a lookup in the value_array_list with array_key (what's between the percentage sings). If value_array_list is not provided then attempt to fetch variable values the number of levels up given by upvar_level (defaults to 3 because this proc is typically invoked from the underscore lookup proc). Here is an example: set localized_message "The %animal% jumped across the %barrier%. About 50% of the time, he stumbled, or maybe it was %%20 %times%." set value_list { animal "frog" barrier "fence" } ns_log notice formatted=[format $localized_message $value_list] The output from the example is: The frog jumped across the fence. About 50% of the time, he stumbled, or maybe it was %20 %times%.

Parameters:

localized_message (required)

value_array_list (optional)

upvar_level (optional, defaults to "3")

Partial Call Graph (max 5 caller/called nodes):

Testcases:

message__format

Get all properties of a message in a particular locale.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

-array (required)

Name of an array in the caller's namespace into which you want the message properties delivered.

Returns:

The array will contain the following entries: message_key, package_key, locale, message, deleted_p, sync_time, conflict_p, upgrade_status, creation_date_ansi, creation_user, key_description.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_message_register, upgrade

Returns a list of embedded substitution variables on the form %varname% in a message. This is useful if you want to check that the variables used in a translated message also appear in the en_US message. If not, there's likely to be a typo.

Parameters:

message (required)

A message with embedded %varname% notation

Returns:

The list of variables in the message

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

12 November 2002

Partial Call Graph (max 5 caller/called nodes):

Testcases:

message__get_embedded_vars

This proc is normally accessed through the _ procedure. Returns a translated string for the given locale and message key. If the user is a translator, inserts tags to link to the translator interface. This allows a translator to work from the context of a web page. Messages will have %name% replaced with variables either from substitution_list, if present, or from the caller's namespace (or upvar_level's namespace). Set upvar_level to 0 and substitution_list empty to prevent substitution from happening Note that this proc does not use named parameters, because named parameters are relatively slow, and this is going to get called a whole lot on each request.

Parameters:

locale (required)

Locale (e.g., "en_US") or language (e.g., "en") string. If locale is the empty string ad_conn locale will be used if we are in an HTTP connection, otherwise the system locale (SiteWideLocale) will be used.

key (required)

Unique identifier for this message. Will be the same identifier for each locale. All keys belong to a certain package and should be prefixed with the package key of that package on the format package_key.message_key (the dot is reserved for separating the package key, the rest of the key should contain only alphanumeric characters and underscores). If the key does not belong to any particular package it should not contain a dot. A lookup is always attempted with the exact key given to this proc.

default (optional, defaults to "TRANSLATION MISSING")

Text to return if there is no message in the message catalog for the given locale. This argument is optional. If this argument is not provided or is the empty string then the text returned will be TRANSLATION MISSING - $key.

substitution_list (optional)

A list of values to substitute into the message. This argument should only be given for certain messages that contain place holders (on the syntax %var_name%) for embedding variable values, see lang::message::format. If this list is not provided and the message has embedded variables, then the variable values can be fetched with upvar from the scope calling this proc (see upvar_level).

upvar_level (optional, defaults to "1")

If there are embedded variables and no substitution list provided, this parameter specifies how many levels up to fetch the values of the variables in the message. The default is 1.

translator_mode_p (optional, defaults to "1")

Set to 0 if you do not want this call to honor translator mode. Useful if you're not using this message in the page itself, but e.g. for localization data or for the list of messages on the page.

Returns:

A localized piece of text.

Authors:

Jeff Davis <davis@xarg.net>

Henry Minsky <hqm@arsdigita.com>

Peter Marklund <peter@collaboraid.biz>

See Also:

• _
• lang::message::register

Partial Call Graph (max 5 caller/called nodes):

Testcases:

locale_language_fallback

Return 1 if message exists in given locale, 0 otherwise.

Switches:

-varname (optional)

when specified, return value in this variable

Parameters:

locale (required)

key (required)

Author:

Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_catalog_import_export

Registers a message for a given locale and package. Inserts the message key into the database if it doesn't already exists. Inserts the message itself in the given locale into the database if it doesn't exist and updates it if it does. Also updates the cache with the message.

Switches:

-update_sync (optional, boolean)

If this switch is provided the sync_time of the message will be set to current time. The sync time for a message should only be not null when we know that message in catalog file and db are identical (in sync). This message is then used as a merge base for message catalog upgrades. For more info, see the lang::catalog::upgrade proc.

-upgrade_status (optional, defaults to "no_upgrade")

Set the upgrade status of the new message to "added", "updated", "deleted". Defaults to "no_upgrade".

-conflict (optional, boolean)

Set this switch if the upgrade represents a conflict between changes made in the database and in catalog files.

-comment (optional)

-object_id (optional)

Bind this message key to an acs_object, so that upon deletion, the message key will be removed as well.

Parameters:

locale (required)

Locale or language of the message. If a language is supplied, the default locale for the language is looked up.

package_key (required)

The package key of the package that the message belongs to.

message_key (required)

The key that identifies the message within the package.

message (required)

The message text

Authors:

Jeff Davis

Peter Marklund

Bruno Mattarollo <bruno.mattarollo@ams.greenpeace.org>

Christian Hvid

See Also:

• _mr
• lang::message::lookup
• _

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_message_register, locale_language_fallback, localize

Unregisters a message key, i.e. deletes it along with all its messages from the database and deleted entries in the cache. This proc is useful when installing a package. To delete an individual message, as opposed to the entire key, use lang::message::delete.

Parameters:

package_key (required)

message_key (required)

Author:

Peter Marklund

See Also:

• lang::message::delete

Partial Call Graph (max 5 caller/called nodes):

Testcases:

util__replace_temporary_tags_with_lookups, upgrade, localize, group_localization

Update the description of a message key.

Switches:

-package_key (required)

-message_key (required)

-description (required)

Author:

Simon Carstensen

Created:

2003-08-12

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_catalog_import_export