• Publicity: Public Only All

lang-message-procs.tcl

Routines for displaying web pages in multiple languages

This is free software distributed under the terms of the GNU Public License. Full text of the license is available from the GNU Project: http://www.fsf.org/copyleft/gpl.html

Location:
packages/acs-lang/tcl/lang-message-procs.tcl
Created:
10 September 2000
Authors:
Jeff Davis <davis@xarg.net>
Bruno Mattarollo <bruno.mattarollo@ams.greenpeace.org>
Peter Marklund <peter@collaboraid.biz>
Lars Pind <lars@collaboraid.biz>
CVS Identification:
$Id: lang-message-procs.tcl,v 1.68.2.21 2022/02/01 13:23:08 antoniop Exp $

Procedures in this file

Detailed information

_ (public)

 _ key [ substitution_list ]

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]]
If the message value is "To view this item, please click here: %item_url%", then the URL will be insert into the message.

Parameters:
key - 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:

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_subsite_group_type acs_subsite_group_type (test acs-subsite) _ _ test_acs_subsite_group_type->_ test_group_localization group_localization (test acs-subsite) test_group_localization->_ Class ::Generic::Form Class ::Generic::Form (public) Class ::Generic::Form->_ Class ::Generic::List Class ::Generic::List (public) Class ::Generic::List->_ Class ::xo::db::Class Class ::xo::db::Class (public) Class ::xo::db::Class->_ Class ::xo::db::CrClass Class ::xo::db::CrClass (public) Class ::xo::db::CrClass->_ Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->_

Testcases:
group_localization, acs_subsite_group_type

lang::message::cache (public)

 lang::message::cache

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

Partial Call Graph (max 5 caller/called nodes):
%3 lang::catalog::import lang::catalog::import (public) lang::message::cache lang::message::cache lang::catalog::import->lang::message::cache lang::message::lookup lang::message::lookup (public) lang::message::lookup->lang::message::cache lang::message::message_exists_p lang::message::message_exists_p (public) lang::message::message_exists_p->lang::message::cache packages/acs-admin/www/apm/version-i18n-process-2.tcl packages/acs-admin/ www/apm/version-i18n-process-2.tcl packages/acs-admin/www/apm/version-i18n-process-2.tcl->lang::message::cache packages/acs-lang/tcl/acs-lang-init.tcl packages/acs-lang/ tcl/acs-lang-init.tcl packages/acs-lang/tcl/acs-lang-init.tcl->lang::message::cache

Testcases:
No testcase defined.

lang::message::check (public)

 lang::message::check locale package_key message_key message

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
package_key
message_key
message

Partial Call Graph (max 5 caller/called nodes):
%3 test_lang_messages_correct lang_messages_correct (test acs-lang) lang::message::check lang::message::check test_lang_messages_correct->lang::message::check lang::message::register lang::message::register (public) lang::message::register->lang::message::check packages/acs-lang/www/admin/edit-localized-message.tcl packages/acs-lang/ www/admin/edit-localized-message.tcl packages/acs-lang/www/admin/edit-localized-message.tcl->lang::message::check

Testcases:
lang_messages_correct

lang::message::delete (public)

 lang::message::delete -package_key package_key \
    -message_key message_key -locale locale

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):
%3 test_test_message_register test_message_register (test acs-lang) lang::message::delete lang::message::delete test_test_message_register->lang::message::delete lang::message::edit lang::message::edit (private) lang::message::edit->lang::message::delete lang::message::unregister lang::message::unregister (public) lang::message::unregister->lang::message::delete lang::test::execute_upgrade lang::test::execute_upgrade (private) lang::test::execute_upgrade->lang::message::delete packages/acs-lang/www/admin/message-delete.tcl packages/acs-lang/ www/admin/message-delete.tcl packages/acs-lang/www/admin/message-delete.tcl->lang::message::delete

Testcases:
test_message_register

lang::message::embedded_vars_regexp (public)

 lang::message::embedded_vars_regexp

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):
%3 lang::message::format lang::message::format (public) lang::message::embedded_vars_regexp lang::message::embedded_vars_regexp lang::message::format->lang::message::embedded_vars_regexp lang::message::get_embedded_vars lang::message::get_embedded_vars (public) lang::message::get_embedded_vars->lang::message::embedded_vars_regexp template::expand_percentage_signs template::expand_percentage_signs (public) template::expand_percentage_signs->lang::message::embedded_vars_regexp

Testcases:
No testcase defined.

lang::message::format (public)

 lang::message::format localized_message [ value_array_list ] \
    [ upvar_level ]

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
value_array_list (optional)
upvar_level (defaults to "3")

Partial Call Graph (max 5 caller/called nodes):
%3 test_message__format message__format (test acs-lang) lang::message::format lang::message::format test_message__format->lang::message::format lang::message::lookup lang::message::lookup (public) lang::message::lookup->lang::message::format

Testcases:
message__format

lang::message::get (public)

 lang::message::get -package_key package_key -message_key message_key \
    -locale locale -array array

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):
%3 test_test_message_register test_message_register (test acs-lang) lang::message::get lang::message::get test_test_message_register->lang::message::get test_upgrade upgrade (test acs-lang) test_upgrade->lang::message::get lang::message::edit lang::message::edit (private) lang::message::edit->lang::message::get lang::message::get_element lang::message::get_element (private) lang::message::get_element->lang::message::get lang::message::register lang::message::register (public) lang::message::register->lang::message::get lang::test::check_import_result lang::test::check_import_result (private) lang::test::check_import_result->lang::message::get lang::test::execute_upgrade lang::test::execute_upgrade (private) lang::test::execute_upgrade->lang::message::get

Testcases:
test_message_register, upgrade

lang::message::get_embedded_vars (public)

 lang::message::get_embedded_vars message

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 - 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):
%3 test_message__get_embedded_vars message__get_embedded_vars (test acs-lang) lang::message::get_embedded_vars lang::message::get_embedded_vars test_message__get_embedded_vars->lang::message::get_embedded_vars lang::message::check lang::message::check (public) lang::message::check->lang::message::get_embedded_vars

Testcases:
message__get_embedded_vars

lang::message::lookup (public)

 lang::message::lookup locale key [ default ] [ substitution_list ] \
    [ upvar_level ] [ translator_mode_p ]

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 - 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 - 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 (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 (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 (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:

Partial Call Graph (max 5 caller/called nodes):
%3 test_locale_language_fallback locale_language_fallback (test acs-lang) lang::message::lookup lang::message::lookup test_locale_language_fallback->lang::message::lookup Class ::xowiki::formfield::FormField Class ::xowiki::formfield::FormField (public) Class ::xowiki::formfield::FormField->lang::message::lookup _ _ (public) _->lang::message::lookup auth::local::registration::Register auth::local::registration::Register (private) auth::local::registration::Register->lang::message::lookup forum::format::reply_subject forum::format::reply_subject (public) forum::format::reply_subject->lang::message::lookup lang::message::check lang::message::check (public) lang::message::check->lang::message::lookup

Testcases:
locale_language_fallback

lang::message::message_exists_p (public)

 lang::message::message_exists_p [ -varname varname ] locale key

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

Switches:
-varname (optional)
when specified, return value in this variable
Parameters:
locale
key
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 adp_parse_ad_conn_file adp_parse_ad_conn_file (public) lang::message::message_exists_p lang::message::message_exists_p adp_parse_ad_conn_file->lang::message::message_exists_p apm::package_version::attributes::set_all_instances_names apm::package_version::attributes::set_all_instances_names (private) apm::package_version::attributes::set_all_instances_names->lang::message::message_exists_p lang::message::check lang::message::check (public) lang::message::check->lang::message::message_exists_p lang::message::lookup lang::message::lookup (public) lang::message::lookup->lang::message::message_exists_p packages/acs-lang/lib/messages-to-translate.tcl packages/acs-lang/ lib/messages-to-translate.tcl packages/acs-lang/lib/messages-to-translate.tcl->lang::message::message_exists_p

Testcases:
No testcase defined.

lang::message::register (public)

 lang::message::register [ -update_sync ] \
    [ -upgrade_status upgrade_status ] [ -conflict ] \
    [ -comment comment ] [ -object_id object_id ] locale package_key \
    message_key message

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 (boolean) (optional)
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 (defaults to "no_upgrade") (optional)
Set the upgrade status of the new message to "added", "updated", "deleted". Defaults to "no_upgrade".
-conflict (boolean) (optional)
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 - Locale or language of the message. If a language is supplied, the default locale for the language is looked up.
package_key - The package key of the package that the message belongs to.
message_key - The key that identifies the message within the package.
message - The message text
Authors:
Jeff Davis
Peter Marklund
Bruno Mattarollo <bruno.mattarollo@ams.greenpeace.org>
Christian Hvid

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_locale_language_fallback locale_language_fallback (test acs-lang) lang::message::register lang::message::register test_locale_language_fallback->lang::message::register test_localize localize (test acs-lang) test_localize->lang::message::register test_test_message_register test_message_register (test acs-lang) test_test_message_register->lang::message::register _mr _mr (private, deprecated) _mr->lang::message::register lang::catalog::import_messages lang::catalog::import_messages (private) lang::catalog::import_messages->lang::message::register lang::catalog::translate lang::catalog::translate (private) lang::catalog::translate->lang::message::register lang::message::revert lang::message::revert (private) lang::message::revert->lang::message::register lang::test::execute_upgrade lang::test::execute_upgrade (private) lang::test::execute_upgrade->lang::message::register

Testcases:
test_message_register, locale_language_fallback, localize

lang::message::unregister (public)

 lang::message::unregister package_key message_key

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
message_key
Author:
Peter Marklund

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_group_localization group_localization (test acs-subsite) lang::message::unregister lang::message::unregister test_group_localization->lang::message::unregister test_localize localize (test acs-lang) test_localize->lang::message::unregister test_upgrade upgrade (test acs-lang) test_upgrade->lang::message::unregister test_util__replace_temporary_tags_with_lookups util__replace_temporary_tags_with_lookups (test acs-lang) test_util__replace_temporary_tags_with_lookups->lang::message::unregister group::delete group::delete (public) group::delete->lang::message::unregister packages/acs-lang/www/admin/message-unregister.tcl packages/acs-lang/ www/admin/message-unregister.tcl packages/acs-lang/www/admin/message-unregister.tcl->lang::message::unregister rel_types::delete_role rel_types::delete_role (public) rel_types::delete_role->lang::message::unregister

Testcases:
util__replace_temporary_tags_with_lookups, upgrade, localize, group_localization

lang::message::update_description (public)

 lang::message::update_description -package_key package_key \
    -message_key message_key -description description
Switches:
-package_key (required)
-message_key (required)
-description (required)
Author:
Simon Carstensen
Created:
2003-08-12

Partial Call Graph (max 5 caller/called nodes):
%3 lang::catalog::import_from_file lang::catalog::import_from_file (private) lang::message::update_description lang::message::update_description lang::catalog::import_from_file->lang::message::update_description packages/acs-lang/www/admin/edit-description.tcl packages/acs-lang/ www/admin/edit-description.tcl packages/acs-lang/www/admin/edit-description.tcl->lang::message::update_description

Testcases:
No testcase defined.
[ show source ]