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

Testcases:

group_localization, acs_subsite_group_type

Registers a message in a given locale or language. Inserts the message into the table lang_messages if it does not exist and updates if it does. It assumes that the key is the concatenation of message and package key like this: package_key.message_key Actually, there is very little need for this proc (which is not used in the 300+ packages in the repository), therefore, it is marked as deprecated. Use lang::message::register instead.

Parameters:

locale (required)

Abbreviation for language of the message or the locale.

key (required)

Unique identifier for this message. Will be the same identifier for each language

message (required)

Text of the message

See Also:

• lang::message::register

Testcases:

No testcase defined.

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

Switches:

-force (optional, boolean)

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)

Testcases:

lang_messages_correct

Return the number of messages with conflicts (conflict_p=t) resulting from catalog imports.

Switches:

-package_key (optional)

Restrict count to package with this key

-locale (optional)

Restrict count to messages of this locale

Author:

Peter Marklund

Testcases:

No testcase defined.

Deletes a message in a particular locale.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

Author:

Lars Pind <lars@collaboraid.biz>

Testcases:

test_message_register

Edit properties (meta data) of a language catalog message, but not the message text itself. To update or add message catalog text, use the lang::message::register proc. Implementation note: some of the dynamic sql edit code of this proc was copied from the auth::authority::edit proc and should probably be broken out into a general API.

Switches:

-update_sync (optional, boolean)

If this switch is provided the sync_time of the message will be updated to current time. If not provided no update to sync_time will be made. If sync_time is contained in the edit_array_list then that value will override the update_sync flag.

Parameters:

package_key (required)

The package_key of the message to update

message_key (required)

The message_key of the message to update

locale (required)

The locale of the message to update

edit_array_list (required)

An array list holding names of columns and the values to set them to. Valid keys in this array list are any column names in the lang_messages table.

Author:

Peter Marklund

Testcases:

upgrade

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

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

12 November 2002

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")

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>

Testcases:

test_message_register, upgrade

Get value of a single attribute of a message.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

-element (required)

The name of the attribute that you want.

Author:

Peter Marklund

See Also:

• lang::message::get

Testcases:

No testcase defined.

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

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

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

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
• _

Testcases:

test_message_register, locale_language_fallback, localize

Delete a certain message key from the cache for all locales.

Parameters:

package_key (required)

message_key (required)

Author:

Peter Marklund

Testcases:

No testcase defined.

Revert a message to the last overwritten version of it, i.e. revert the last change.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

Author:

Peter Marklund

Testcases:

No testcase defined.

Undeletes a message from a particular locale.

Switches:

-package_key (required)

-message_key (required)

-locale (required)

Author:

Héctor Romojaro

Testcases:

No testcase defined.

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

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

Testcases:

test_catalog_import_export