lang::message::lookup (public)

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

Defined in packages/acs-lang/tcl/lang-message-procs.tcl

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

Source code:

    # Make sure messages are in the cache
    acs::per_thread_cache eval -key acs-lang.message_cache_loaded {
        lang::message::cache
    }

    # Make sure that a default of "" is transformed into Translation Missing
    # As per discussion on IRC on 2008-03-06
    if { $default eq ""} {
        set default "TRANSLATION MISSING"
    }

    if { $locale eq "" } {
        # No locale provided

        if { [ns_conn isconnected] } {
            # We are in an HTTP connection (request) so use that locale
            set locale [ad_conn locale]
        } else {
            # There is no HTTP connection - resort to system locale
            set locale [lang::system::locale]
        }
    } elseif { [string length $locale] == 2 } {
        # Only language provided, let's get the default locale for this language
        set default_locale [lang::util::default_locale_from_lang $locale]
        if { $default_locale eq "" } {
            error "Could not look up locale for language $locale"
        } else {
            set locale $default_locale
        }
    }

    #
    # Probably, we should check for undefined locales passed in. We
    # omit this for now due to missing performance evaluation of this
    # change.
    #
    # elseif {$locale ni [lang::system::get_locales]} {
    #    error "Unknown locale $locale passed as argument"
    #}

    #
    # Trying locale directly
    #
    if { ![message_exists_p -varname message $locale $key] } {
        #
        # Trying default locale for language.
        #
        set language [lindex [split $locale "_"] 0]

        #
        # When the lookup returns empty (no locale for this language),
        # or returns the same language we checked before, there is no
        # reason for the message lookup and we can go to the next
        # test.
        #
        set lang_locale [lang::util::default_locale_from_lang $language]
        if { $lang_locale eq ""
             || $lang_locale eq $locale
             || ![message_exists_p -varname message $lang_locale $key]
         } {
            #
            # Trying system locale for package
            #
            if { ![message_exists_p -varname message [lang::system::locale] $key] } {
                #
                # Trying site-wide system locale
                #
                if { ![message_exists_p -varname message [lang::system::locale -site_wide] $key] } {
                    #
                    # Resorting to en_US
                    #
                    if { ![message_exists_p -varname message "en_US" $key] } {
                        if {"TRANSLATION MISSING" ne $default} {
                            set message $default
                        } else {
                            ad_log Error "lang::message::lookup: Key '$key' does not exist in en_US"
                            set message "MESSAGE KEY MISSING: '$key'"
                        }
                    }
                }
            }
        }
    }

    # Do any variable substitutions (interpolation of variables)
    # Set upvar_level to 0 and substitution_list empty to prevent substitution from happening
    if { [llength $substitution_list] > 0 || ($upvar_level >= 1 && [string first "%" $message] != -1) } {
        set message [lang::message::format $message $substitution_list [expr {$upvar_level + 1}]]
    }

    if { [lang::util::translator_mode_p] } {
        # Translator mode - record the message lookup
        lang::util::record_message_lookup $key

        if { $translator_mode_p } {
            global message_key_num
            if { ![info exists message_key_num] } {
                set message_key_num 1
            } else {
                incr message_key_num
            }

            # encode the key in the page
            set message "$message\x02(\x01$key\x01)\x02"
        }
    }

    return $message

Generic XQL file:

packages/acs-lang/tcl/lang-message-procs.xql

PostgreSQL XQL file:

packages/acs-lang/tcl/lang-message-procs-postgresql.xql

Oracle XQL file:

packages/acs-lang/tcl/lang-message-procs-oracle.xql