14 APEX_LANG

You can use APEX_LANG API to translate messages.

Topics:

CREATE_LANGUAGE_MAPPING Procedure

Use this procedure to create the language mapping for the translation of an application. Translated applications are published as new applications, but are not directly editable in the Application Builder.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.CREATE_LANGUAGE_MAPPING (
  p_application_id IN NUMBER,
  p_language IN VARCHAR2,
  p_translation_application_id IN NUMBER )

Parameters

Table 14-1 CREATE_LANGUAGE_MAPPING Parameters

Parameter Description

p_application_id

The ID of the application for which you want to create the language mapping. This is the ID of the primary language application.

p_language

The IANA language code for the mapping. Examples include en-us, fr-ca, ja, he.

p_translation_application_id

Unique integer value for the ID of the underlying translated application. This number cannot end in 0.


Example

The following example demonstrates the creation of the language mapping for an existing Application Express application.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;

    -- Now, actually create the language mapping
    apex_lang.create_language_mapping(
        p_application_id => 63969,
        p_language => 'ja',
        p_translation_application_id => 778899 );
    commit;
    --
    -- Print what we just created to confirm
    --
    for c1 in (select *
                 from apex_application_trans_map
                where primary_application_id = 63969) loop
        dbms_output.put_line( 'translated_application_id: ' || c1.translated_application_id );
        dbms_output.put_line( 'translated_app_language: ' || c1.translated_app_language );
    end loop;
end;
/

DELETE_LANGUAGE_MAPPING Procedure

Use this procedure to delete the language mapping for the translation of an application. This procedure deletes all translated strings in the translation repository for the specified language and mapping. Translated applications are published as new applications, but are not directly editable in the Application Builder.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.DELETE_LANGUAGE_MAPPING (
  p_application_id IN NUMBER,
  p_language IN VARCHAR2 )

Parameters

Table 14-2 DELETE_LANGUAGE_MAPPING Parameters

Parameter Description

p_application_id

The ID of the application for which you want to delete the language mapping. This is the ID of the primary language application.

p_language

The IANA language code for the existing mapping. Examples include en-us, fr-ca, ja, he.


Example

The following example demonstrates the deletion of the language mapping for an existing Application Express application and existing translation mapping.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
     end loop;
    -- Now, delete the language mapping
    apex_lang.delete_language_mapping(
        p_application_id => 63969,
        p_language => 'ja' );
    commit;
    --
    -- Print what we just updated to confirm
    --
    for c1 in (select count(*) thecount
                 from apex_application_trans_map
                where primary_application_id = 63969) loop
        dbms_output.put_line( 'Translation mappings found: ' || c1.thecount );
    end loop;
end;
/

LANG Function

Use this function to return a translated text string for translations defined in dynamic translations.

Syntax

APEX_LANG.LANG (
    p_primary_text_string IN VARCHAR2 DEFAULT NULL,
    p0 IN VARCHAR2 DEFAULT NULL,
    p1 IN VARCHAR2 DEFAULT NULL,
    p2 IN VARCHAR2 DEFAULT NULL,
    ...
    p9 IN VARCHAR2 DEFAULT NULL,
    p_primary_language IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 14-3 describes the parameters available in the APEX_LANG.LANG function.

Table 14-3 LANG Parameters

Parameter Description

p_primary_text_string

Text string of the primary language. This is the value of the Translate From Text in the dynamic translation.

p0 through p9

Dynamic substitution value: p0 corresponds to %0 in the translation string; p1 corresponds to %1 in the translation string; p2 corresponds to %2 in the translation string, and so on.

p_primary_language

Language code for the message to be retrieved. If not specified, Oracle Application Express uses the current language for the user as defined in the Application Language Derived From attribute.

See also: Specifying the Primary Language for an Application in the Oracle Application Express Application Builder User's Guide.


Example

Suppose you have a table that defines all primary colors. You could define a dynamic message for each color and then apply the LANG function to the defined values in a query. For example:

SELECT APEX_LANG.LANG(color)
FROM my_colors

If you were running the application in German, RED was a value for the color column in the my_colors table, and you defined the German word for red, the previous example would return ROT.

MESSAGE Function

Use this function to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures, and functions.

Syntax

APEX_LANG.MESSAGE (
    p_name IN VARCHAR2 DEFAULT NULL,
    p0 IN VARCHAR2 DEFAULT NULL,
    p1 IN VARCHAR2 DEFAULT NULL,
    p2 IN VARCHAR2 DEFAULT NULL,
    ...
    p9 IN VARCHAR2 DEFAULT NULL,
    p_lang IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 14-4 describes the parameters available in the APEX_LANG.MESSAGE function.

Table 14-4 MESSAGE Parameters

Parameter Description

p_name

Name of the message as defined in Text Messages under Shared Components of your application in Oracle Application Express.

p0 through p9

Dynamic substitution value: p0 corresponds to %0 in the translation string; p1 corresponds to %1 in the translation string; p2 corresponds to %2 in the translation string, and so on.

p_lang

Language code for the message to be retrieved. If not specified, Oracle Application Express uses the current language for the user as defined in the Application Language Derived From attribute.

See also: Specifying the Primary Language for an Application in the Oracle Application Express Application Builder User's Guide.


Example

The following example assumes you have defined a message called GREETING_MSG in your application in English as "Good morning %0" and in German as "Guten Tag %1". The following example demonstrates how you could invoke this message from PL/SQL:

BEGIN
--
-- Print the greeting
--
HTP.P(APEX_LANG.MESSAGE('GREETING_MSG', V('APP_USER')));
END;

How the p_lang attribute is defined depends on how the Application Express engine derives the Application Primary Language. For example, if you are running the application in German and the previous call is made to the APEX_LANG.MESSAGE API, the Application Express engine first looks for a message called GREETING_MSG with a LANG_CODE of de. If it does not find anything, then it is reverted to the Application Primary Language attribute. If it still does not find anything, the Application Express engine looks for a message by this name with a language code of en.

PUBLISH_APPLICATION Procedure

Use this procedure to publish the translated version of an application. This procedure creates an underlying, hidden replica of the primary application and merges the strings from the translation repository in this new application. Perform a seed and publish process each time you want to update the translated version of your application and synchronize it with the primary application.

This application is not visible in the Application Builder. It can be published and exported, but not directly edited.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.PUBLISH_APPLICATION (
  p_application_id IN NUMBER,
  p_language IN VARCHAR2 )

Parameters

Table 14-5 PUBLISH_APPLICATION Parameters

Parameter Description

p_application_id

The ID of the application for which you want to publish and create the translated version. This is the ID of the primary language application.

p_language

The IANA language code for the existing translation mapping. Examples include en-us, fr-ca, ja, he.


Example

The following example demonstrates the publish process for an Application Express application and language.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;
    -- Now, publish the translated version of the application
    apex_lang.publish_application(
        p_application_id => 63969,
        p_language => 'ja' );
    commit;
end;
/

SEED_TRANSLATIONS Procedure

Use this procedure to seed the translation repository for the specified application and language. This procedure populates the translation repository with all of the new, updated and removed translatable strings from your application. Perform a seed and publish process each time you want to update the translated version of your application and synchronize it with the primary application.

Syntax

APEX_LANG.SEED_TRANSLATIONS (
  p_application_id IN NUMBER,
  p_language IN VARCHAR2 )

Parameters

Table 14-6 SEED_TRANSLATIONS Parameters

Parameter Description

p_application_id

The ID of the application for which you want to update the translation repository. This is the ID of the primary language application.

p_language

The IANA language code for the existing translation mapping. Examples include en-us, fr-ca, ja, he.


Example

The following example demonstrates the seeding process of the translation repository for an Application Express application and language.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;
    -- Now, seed the translation repository
    apex_lang.seed_translations(
        p_application_id => 63969,
        p_language => 'ja' );
    commit;
    -- Print out the total number of potentially translatable strings
    --
    for c1 in (select count(*) thecount
                 from apex_application_trans_repos
                where application_id = 63969) loop
        dbms_output.put_line( 'Potentially translatable strings found: ' || c1.thecount );
    end loop;
end;
/

UPDATE_LANGUAGE_MAPPING Procedure

Use this procedure to update the language mapping for the translation of an application. Translated applications are published as new applications, but are not directly editable in the Application Builder.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.UPDATE_LANGUAGE_MAPPING (
  p_application_id IN NUMBER,
  p_language IN VARCHAR2,
  p_new_trans_application_id IN NUMBER )

Parameters

Table 14-7 UPDATE_LANGUAGE_MAPPING Parameters

Parameters Description

p_application_id

The ID of the application for which you want to update the language mapping. This is the ID of the primary language application.

p_language

The IANA language code for the existing mapping. Examples include en-us, fr-ca, ja, he. The language of the mapping cannot be updated with this procedure, only the new translation application ID.

p_new_trans_application_id

New unique integer value for the ID of the underlying translated application. This number cannot end in 0.


Example

The following example demonstrates the update of the language mapping for an existing Application Express application and existing translation mapping.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;
    -- Now, update the language mapping
    apex_lang.update_language_mapping(
        p_application_id => 63969,
        p_language => 'ja',
        p_new_trans_application_id => 881188 );
    commit;
    --
    -- Print what we just updated to confirm
    --
    for c1 in (select *
                 from apex_application_trans_map
                where primary_application_id = 63969) loop
        dbms_output.put_line( 'translated_application_id: ' || c1.translated_application_id );
        dbms_output.put_line( 'translated_app_language: ' || c1.translated_app_language );
    end loop;
end;
/

UPDATE_MESSAGE Procedure

Use this procedure to update a translatable text message for the specified application.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.UPDATE_MESSAGE (
  p_id IN NUMBER,
  p_message_text IN VARCHAR2 )

Parameters

Table 14-8 UPDATE_MESSAGE Parameters

Parameter Description

p_id

The ID of the text message.

p_message_text

The new text for the translatable text message.


Example

The following example demonstrates an update of an existing translatable text message.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;
    -- Locate the ID of the specific message and update it with the new text
    for c1 in (select translation_entry_id
                 from apex_application_translations
                where application_id = 63969
                  and translatable_message = 'TOTAL_COST'
                  and language_code = 'ja') loop
        apex_lang.update_message(
            p_id => c1.translation_entry_id,
            p_message_text => 'The total cost is: %0');
        commit;
        exit;
    end loop;
end;
/

UPDATE_TRANSLATED_STRING Procedure

Use this procedure to update a translated string in the seeded translation repository.

Note:

This procedure is available in Application Express release 4.2.3 and later.

Syntax

APEX_LANG.UPDATE_TRANSLATED_STRING (
  p_id IN NUMBER,
  p_language IN VARCHAR2
  p_string IN VARCHAR2 )

Parameters

Table 14-9 UPDATE_TRANSLATED_STRING Parameters

Parameter Description

p_id

The ID of the string in the translation repository.

p_language

The IANA language code for the existing translation mapping. Examples include en-us, fr-ca, ja, he. The language of the mapping cannot be updated with this procedure, only the new translation application ID.

p_string

The new value for the string in the translation repository.


Example

The following example demonstrates an update of an existing string in the translation repository.

begin
    --
    -- If running from SQL*Plus, we need to set the environment
    -- for the Application Express workspace associated with this schema. The
    -- call to apex_util.set_security_group_id is not necessary if
    -- you're running within the context of the Application Builder
    -- or an Application Express application.
    --
    for c1 in (select workspace_id
                 from apex_workspaces) loop
        apex_util.set_security_group_id( c1.workspace_id );
        exit;
    end loop;
    -- Locate all strings in the repository for the specified application
    -- which are 'Search' and change to 'Find'
    for c1 in (select id
                 from apex_application_trans_repos
                where application_id = 63969
                  and dbms_lob.compare(from_string, to_nclob('Search')) = 0
                  and language_code = 'ja') loop
        apex_lang.update_translated_string(
            p_id => c1.id,
            p_language => 'ja',
            p_string => 'Find');
        commit;
        exit;
    end loop;
end;
/