How Do I Translate Messages in Oracle APEX

 

Introduction
Translating messages in Oracle APEX is a crucial step in building applications that effectively communicate with users in their preferred language. Messages include validation errors, success notifications, prompts, and other dynamic content that guide user interactions. Proper translation of these messages ensures clarity, improves usability, and creates a more inclusive experience for a global audience.

Translating messages in Oracle APEX is essential to provide users with clear, localized feedback such as validation errors, success notifications, prompts, and system messages. Oracle APEX offers a structured approach to translating these messages using the Text Messages feature and the application translation framework.

Here is a detailed process on how to translate messages in Oracle APEX:

1. Access Text Messages Repository
   Navigate to Shared Components > Text Messages in your application. This repository contains key-value pairs where each key represents a message name, and the value is the message text in the primary language.

2. Create or Identify Messages to Translate
   You can either create new messages for your application’s dynamic content or use existing ones. Messages may include:

   • Validation error texts

   • Custom informational messages

   • Confirmation prompts

3. Assign Language-Specific Translations
   Oracle APEX allows you to define translations for each message by language. When you create or edit a text message, you can add translations for the languages supported by your application.

   • Select the message key.

   • Add or edit translations by choosing the language code (e.g., fr for French).

   • Enter the translated message text.

4. Use Messages in Your Application
   To display translated messages dynamically, use the APEX_LANG.MESSAGE API in your PL/SQL code or processes. For example:

   DECLARE
     l_msg VARCHAR2(4000);
   BEGIN
     l_msg := APEX_LANG.MESSAGE('MY_CUSTOM_ERROR');
     APEX_ERROR.ADD_ERROR(
       p_message => l_msg,
       p_display_location => apex_error.c_inline_in_notification);
   END;
   

   This approach retrieves the correct translation for the current session language automatically.

5. Export and Import Translations
   To manage translations efficiently, use the Translate Application feature under Shared Components:

   • Export the XLIFF file for the target language, which includes text messages.

   • Translate the messages in the XLIFF file using a supported tool or text editor.

   • Import the translated XLIFF back into APEX, which updates all message translations in bulk.

6. Test Translated Messages
   Change the application’s session language to verify that messages appear correctly in different languages. Ensure placeholders and substitution variables within messages remain intact and render properly.

7. Maintain Consistency
   For consistent translations across the application, standardize message keys and their usage. Reuse text messages for common prompts and errors to avoid duplication and ensure uniformity.

By leveraging Oracle APEX’s Text Messages and translation framework, you can deliver precise, culturally appropriate feedback to users. This enhances the overall user experience and makes your application truly multilingual and accessible worldwide.

Oracle APEX allows developers to translate messages within an application to support multiple languages. These messages include system-generated notifications, error messages, success messages, and custom messages defined by the developer. Translating messages ensures that users receive information in their preferred language.

Understanding Translatable Messages

Messages in Oracle APEX that may require translation include:

• System Messages – Standard error messages and notifications generated by APEX

• Validation Messages – Custom messages displayed when form validations fail

• Success Messages – Confirmation messages after successful actions

• Warning or Informational Messages – Alerts triggered by Dynamic Actions or PL/SQL processes

• Custom Messages – Messages stored in APEX_TEXT_MESSAGE for dynamic retrieval

Oracle APEX provides Globalization and Translation tools to translate these messages into multiple languages.

Step 1: Creating a Language Mapping

Before translating messages, define the primary and target languages for the application.

1. Open the APEX application.

2. Navigate to Shared Components > Globalization > Translate Application.

3. Click Create Language Mapping.

4. Select the Primary Language and the Target Language.

5. Click Create to establish the mapping.

This allows APEX to create and manage translations for the selected languages.

Step 2: Seeding Translations

Seeding extracts all translatable text, including system and custom messages.

1. Go to Shared Components > Globalization > Translate Application.

2. Click Seed Translations.

3. Select the Application ID and the Target Language.

4. Click Seed Translations to populate the repository.

After seeding, APEX extracts all messages into the Translation Repository.

Step 3: Exporting the XLIFF File

APEX stores translatable text in XLIFF (XML Localization Interchange File Format) files.

1. Navigate to Shared Components > Globalization > Translate Application.

2. Click Export XLIFF File.

3. Choose the Target Language and download the file.

This XLIFF file contains all messages requiring translation, structured as:

<trans-unit id="VALIDATION_ERROR">

    <source>Please enter a valid email address.</source>

    <target></target>

</trans-unit>

<trans-unit id="SUCCESS_MESSAGE">

    <source>Record saved successfully.</source>

    <target></target>

</trans-unit>

Step 4: Translating Messages in the XLIFF File

Edit the XLIFF file and provide translations within the <target> tags.

Example:

<trans-unit id="VALIDATION_ERROR">

    <source>Please enter a valid email address.</source>

    <target>Por favor ingrese un correo electrónico válido.</target>

</trans-unit>

<trans-unit id="SUCCESS_MESSAGE">

    <source>Record saved successfully.</source>

    <target>Registro guardado exitosamente.</target>

</trans-unit>

Once all messages are translated, save the file.

Step 5: Importing the Translated XLIFF File

1. Go to Shared Components > Globalization > Translate Application.

2. Click Apply XLIFF Document.

3. Select the Target Language and upload the file.

4. Click Apply to import translations.

Step 6: Publishing the Translated Messages

1. Go to Shared Components > Globalization > Translate Application.

2. Click Publish Application.

3. Select the Target Language and confirm.

The translated messages will now appear when users switch to the target language.

Step 7: Using APEX_TEXT_MESSAGE for Custom Messages

For dynamic messages stored in the database, APEX provides the APEX_TEXT_MESSAGE table.

Creating a Translatable Message:

BEGIN

    APEX_LANG.CREATE_MESSAGE (

        p_name      => 'WELCOME_MESSAGE',

        p_message   => 'Welcome to the application!',

        p_workspace => 'MY_WORKSPACE'

    );

END;

Retrieving a Message in PL/SQL

DECLARE

    v_message VARCHAR2(4000);

BEGIN

    v_message := APEX_LANG.MESSAGE('WELCOME_MESSAGE');

    DBMS_OUTPUT.PUT_LINE(v_message);

END;

When the application is translated, APEX_LANG.MESSAGE automatically retrieves the correct language version.

Step 8: Testing Translated Messages

To verify that messages appear correctly:

1. Set the Session Language to the Target Language.

2. Navigate through the application and trigger messages (e.g., form validation errors, success messages).

3. Ensure that all messages are displayed in the selected language.

Best Practices for Translating Messages in APEX

• Regularly seed translations after making UI changes to capture new messages.

• Use consistent terminology across all translations.

• Maintain XLIFF files for future updates.

• Test translations in different browsers and user sessions.

• Use APEX_LANG.MESSAGE for dynamic messages in PL/SQL code.

By following these steps, developers can effectively translate messages in Oracle APEX, ensuring a smooth multilingual experience for users.

 Conclusion
By translating messages in Oracle APEX, you enable your application to provide meaningful feedback to users across different languages and cultures. Utilizing APEX’s built-in translation tools and text message repositories helps maintain consistency and accuracy throughout your application. This careful attention to message translation enhances user satisfaction and supports the development of truly multilingual applications.