You can use APEX_LANG API to translate messages.
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.APEX_LANG.CREATE_LANGUAGE_MAPPING ( p_application_id IN NUMBER, p_language IN VARCHAR2, p_translation_application_id IN NUMBER )
Table 14-1 CREATE_LANGUAGE_MAPPING Parameters
| Parameter | Description |
|---|---|
|
|
The ID of the application for which you want to create the language mapping. This is the ID of the primary language application. |
|
|
The IANA language code for the mapping. Examples include en-us, fr-ca, ja, he. |
|
|
Unique integer value for the ID of the underlying translated application. This number cannot end in 0. |
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;
/
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.APEX_LANG.DELETE_LANGUAGE_MAPPING ( p_application_id IN NUMBER, p_language IN VARCHAR2 )
Table 14-2 DELETE_LANGUAGE_MAPPING Parameters
| Parameter | Description |
|---|---|
|
|
The ID of the application for which you want to delete the language mapping. This is the ID of the primary language application. |
|
|
The IANA language code for the existing mapping. Examples include en-us, fr-ca, ja, he. |
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;
/
Use this function to return a translated text string for translations defined in dynamic translations.
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;
Table 14-3 describes the parameters available in the APEX_LANG.LANG function.
| Parameter | Description |
|---|---|
|
|
Text string of the primary language. This is the value of the Translate From Text in the dynamic translation. |
|
|
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. |
|
|
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. |
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.
Use this function to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures, and functions.
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;
Table 14-4 describes the parameters available in the APEX_LANG.MESSAGE function.
| Parameter | Description |
|---|---|
|
|
Name of the message as defined in Text Messages under Shared Components of your application in Oracle Application Express. |
|
|
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. |
|
|
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. |
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.
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.APEX_LANG.PUBLISH_APPLICATION ( p_application_id IN NUMBER, p_language IN VARCHAR2 )
Table 14-5 PUBLISH_APPLICATION Parameters
| Parameter | Description |
|---|---|
|
|
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. |
|
|
The IANA language code for the existing translation mapping. Examples include en-us, fr-ca, ja, he. |
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;
/
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.
APEX_LANG.SEED_TRANSLATIONS ( p_application_id IN NUMBER, p_language IN VARCHAR2 )
Table 14-6 SEED_TRANSLATIONS Parameters
| Parameter | Description |
|---|---|
|
|
The ID of the application for which you want to update the translation repository. This is the ID of the primary language application. |
|
|
The IANA language code for the existing translation mapping. Examples include en-us, fr-ca, ja, he. |
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;
/
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.APEX_LANG.UPDATE_LANGUAGE_MAPPING ( p_application_id IN NUMBER, p_language IN VARCHAR2, p_new_trans_application_id IN NUMBER )
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. |
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;
/
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.APEX_LANG.UPDATE_MESSAGE ( p_id IN NUMBER, p_message_text IN VARCHAR2 )
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. |
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;
/
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.APEX_LANG.UPDATE_TRANSLATED_STRING ( p_id IN NUMBER, p_language IN VARCHAR2 p_string IN VARCHAR2 )
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. |
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;
/