Translating Applications for Multibyte Languages in Oracle APEX

Introduction
Translating applications for multibyte languages in Oracle APEX is essential when building solutions for users who read and write in languages such as Chinese, Japanese, Korean, Arabic, or Hindi. These languages require special handling because their characters take more than one byte and often have unique display and formatting needs. Oracle APEX fully supports multibyte character sets, allowing developers to create localized applications that are both accurate and culturally appropriate.

Translating applications for multibyte languages in Oracle APEX involves several key steps to ensure that your application can correctly display and manage complex characters such as those used in Chinese, Japanese, Korean, Arabic, and other non-Latin scripts. Oracle APEX fully supports Unicode, which means it can handle multibyte characters natively, but you must follow certain practices to make sure translations appear correctly and consistently.

Step 1: Confirm Character Set Support

First, ensure your Oracle Database is using a character set that supports multibyte characters, such as AL32UTF8. You can check this with the following SQL command:

SELECT value FROM nls_database_parameters WHERE parameter = 'NLS_CHARACTERSET';

If your database does not support Unicode, multibyte characters may display incorrectly or be truncated.

Step 2: Set the Primary Language

In APEX, go to Shared Components > Globalization Attributes and set the Primary Language of the application to the base language (e.g., English). This will be used as the source for translations.

Step 3: Add Target Multibyte Language

Navigate to Shared Components > Language and click Create to add a new language, such as:

• zh-cn for Simplified Chinese

• ja for Japanese

• ko for Korean

• ar for Arabic

Select the appropriate language code and give it a description. This defines the translation target.

Step 4: Export Translation Text

From Shared Components > Translate Application, select the target language and click Export XLIFF File. The XLIFF file is an XML format that contains all text labels, messages, prompts, and button captions from your application.

Download the file and open it in a text editor or translation tool that supports Unicode. Replace the <target> values with translated text using the appropriate multibyte characters. Save the file in UTF-8 format to preserve the encoding.

Step 5: Import Translated XLIFF

Return to APEX and go to Translate Application again. Use the Import XLIFF File function to upload your translated file. APEX will store the translations and associate them with the defined language code.

Step 6: Enable Language Switching

To allow users to switch languages:

• Create a page item (e.g., P0_LANGUAGE) with a list of available languages.

• Set Application Language Derived From to that item (under Globalization Attributes).

• Add a dynamic action to submit and redirect when the language is changed.

Use a Before Header process if you need to manually set the language in PL/SQL:

BEGIN
  APEX_UTIL.SET_SESSION_LANG(:P0_LANGUAGE);
END;

Step 7: Test Layout and Alignment

Multibyte languages such as Arabic (right-to-left) or Chinese (vertically dense) may affect layout spacing, font sizing, and alignment. Make sure to:

• Use web fonts that support the target language’s script

• Enable right-to-left support in page templates if needed

• Test label widths, alignment, and line wrapping

Step 8: Use Text Messages for Dynamic Content

For dynamically generated text, use Shared Components > Text Messages. These allow you to define key-value pairs for translated content:

-- Retrieve translated message
:PX_LABEL := APEX_LANG.MESSAGE('ORDER_SUCCESS');

Each message can have multiple language-specific versions.

By following these steps, Oracle APEX ensures your application displays multibyte characters correctly, supports multiple languages, and allows users to interact with the UI in their preferred script. Proper testing and Unicode handling are critical to maintaining data integrity and visual clarity across different language environments.

Oracle APEX supports building multilingual applications, including those that use multibyte languages such as Chinese, Japanese, and Korean. To ensure proper translation and display of these languages, it is essential to configure the database correctly and use APEX's built-in globalization features.

Configuring the Database for Multibyte Languages

Oracle databases store text using different character sets. To support multiple languages, including multibyte languages, the database should be configured with a Unicode character set such as AL32UTF8.

1. Check the Current Character Set
   Run the following SQL query to determine the current database character set:

SELECT parameter, value 

FROM nls_database_parameters 

WHERE parameter = 'NLS_CHARACTERSET';

If the result is not AL32UTF8, the database may need to be migrated to a Unicode-compatible character set.

2. Configure the Database for Unicode
   If the database does not use AL32UTF8, consider migrating it using Oracle Database Migration Assistant for Unicode or Data Pump Export/Import.

3. Ensure Proper NLS Settings
   Set the session-level NLS (National Language Support) parameters to match the desired language:

ALTER SESSION SET NLS_LANGUAGE = 'JAPANESE';

ALTER SESSION SET NLS_TERRITORY = 'JAPAN';

ALTER SESSION SET NLS_CHARACTERSET = 'AL32UTF8';

Translating Applications in Oracle APEX

Once the database supports multibyte characters, you can configure your APEX application for multilingual support.

1. Enable Globalization in APEX

• Go to Shared Components.

• Select Globalization Attributes.

• Set the Primary Language (e.g., zh-CN for Simplified Chinese).

2. Use XLIFF Translation Files

• Export the translation text as an XLIFF file.

• Translate the strings in the XLIFF file using a text editor or translation software.

• Reimport the translated XLIFF file into APEX.

3. Use the LANG Function
   The LANG function helps dynamically adjust language settings based on the user's session language:

SELECT LANG FROM APEX_APPLICATION_TRANSLATIONS WHERE LANGUAGE_CODE = :SESSION_LANGUAGE;

4. Store Multilingual Data Properly
   When storing multilingual content in the database, ensure that columns use NVARCHAR2 or CLOB data types to handle multibyte characters correctly.

5. Apply Language-Specific Formatting
   Use format masks to display dates, numbers, and currency based on language settings:

ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY/MM/DD';

Testing Multibyte Language Support

1. Switch User Language Preferences

• In APEX User Preferences, change the Language to a multibyte language (e.g., Chinese).

• Verify that text and UI elements render correctly.

2. Test Data Entry and Retrieval

• Insert test records with Chinese, Japanese, or Korean characters.

• Run queries to confirm that multibyte characters are stored and retrieved correctly.

3. Check Browser and OS Language Settings

• Ensure the browser and operating system are configured to display multibyte characters correctly.

Best Practices for Multibyte Language Support

• Use AL32UTF8 as the database character set for full multilingual support.

• Store multilingual text in NVARCHAR2 or CLOB columns.

• Leverage APEX’s Translation Repository to manage multiple language versions efficiently.

• Apply format masks for locale-specific date, number, and currency formatting.

• Always test your application with different languages and user settings to ensure proper display.

By following these steps, you can effectively translate and manage Oracle APEX applications that support multibyte languages like Chinese, Japanese, and Korean.

Conclusion
By properly translating your Oracle APEX application for multibyte languages, you ensure accessibility and clarity for a wider audience. Leveraging Unicode support, translation repositories, and the APEX translation tools, you can deliver multilingual applications that function seamlessly across different languages and regions. With the right setup, your application can support complex scripts while maintaining performance, readability, and consistency.