How to Create a Multi-Language Application in Oracle APEX

Building an application in one language is straightforward, but the real world is multilingual. Whether you are building a SaaS product for global customers or an internal tool for a multinational corporation, your application needs to speak the user's language.

Oracle APEX has a robust, built-in globalization framework that allows you to translate applications without duplicating pages. It uses a "Shadow Application" model where one primary application drives multiple translated versions.

In this guide, we will walk through the entire process: configuring globalization settings, translating static text, handling dynamic data, and allowing users to switch languages on the fly.

Phase 1: Configuring Globalization Attributes in Oracle APEX

Before translating anything, you must tell APEX how to handle languages.

1. Navigate to Shared Components: Open your application and click on Shared Components.
2. Open Globalization Attributes: Under the Globalization section, click on Globalization Attributes.
3. Set Primary Language: Ensure the Application Primary Language is set correctly (e.g., "English (United States) (en-us)").
4. Configure Language Derivation:

Set Application Language Derived From to Session.

Why Session? This gives you the most control, allowing you to change the language programmatically via PL/SQL or URL parameters. Other options like "Browser Language" are less flexible for users who might use a shared computer.

Phase 2: Defining Application Languages in Oracle APEX

Now, define which languages your app will support.

1. Go to Shared Components > Application Translations.
2. Click Define Application Languages.
3. Click Create.
4. Application ID: Enter a unique ID for the shadow application (e.g., if your main app is 100, use 101 for French).
5. Language Code: Select the target language (e.g., fr for French).
6. Click Create. Repeat this for every language you want to support (e.g., 102 for German, 103 for Spanish).

Phase 3: Seeding and Translating Text

This is the core workflow where you extract text and provide translations.

Step 1: Seed Translatable Text

"Seeding" scans your application for every text string (button labels, region titles, item names) and stores them in the internal translation repository.

1. In Application Translations, click Seed Translatable Text.
2. Select the target language (e.g., French) and click Seed.

Step 2: Download XLIFF File

1. Click Download XLIFF Translation Files.
2. Select the language and click Export.
3. This downloads an .xlf file, which is an industry-standard XML format for translation tools.

Step 3: Translate (The Human Part)

Open the XLIFF file in a text editor or a specialized tool (like Poedit). You will see source tags (<source>Hello</source>) and target tags (<target>Bonjour</target>). Fill in the target tags with the correct translations.

Step 4: Upload and Apply

1. Back in APEX, click Apply XLIFF Translation Files.
2. Upload your modified XLIFF file.
3. Click Apply Checked to push the translations into the APEX repository.

Phase 4: Publishing the APEX Application

Your translations are in the database, but users can't see them yet. You must "Publish" the shadow application.

1. In Application Translations, click Publish Translated Applications.
2. Select the language (e.g., French) and click Publish.
3. APEX effectively creates a hidden copy of your app (App 101) that runs the French logic but shares the same data and page structures.

Phase 5: Translating Dynamic Messages (PL/SQL)

Standard translation handles UI labels, but what about error messages or notifications generated in your PL/SQL code?

Using Text Messages

Go to Shared Components > Text Messages.

Create a new message named GREETING_MSG.

Language: English -> Text: "Welcome, %0!"

Language: French -> Text: "Bienvenue, %0!"

Usage in PL/SQL: Instead of hardcoding 'Welcome, ' || :APP_USER, use:

apex_lang.message('GREETING_MSG', :APP_USER)

APEX will automatically pick the correct string based on the user's current session language.

Phase 6: Translating Database Data (Dynamic Translations)

Sometimes, the data inside your tables needs translation (e.g., Product Categories: "Electronics" vs "Électronique").

Define Dynamic Translations:

Go to Shared Components > Translate Application > Dynamic Translations.

Add entries for your data values (e.g., Source: "Electronics", Target: "Électronique", Lang: "fr").

Usage in SQL: Wrap your columns in the APEX_LANG.LANG function in your reports:

SELECT product_id, apex_lang.lang(category_name) as category FROM products

Phase 7: Creating a Language Switcher

Finally, give users a way to change their language preference.

Create a Page Item: Create a Select List item (e.g., P1_LANGUAGE) in the navigation bar or footer.

LOV: Static values DISPLAY_VALUE;RETURN_VALUE -> English;en, French;fr.

Create a Dynamic Action:

• Event: Change of P1_LANGUAGE.

• Action: Execute PL/SQL Code.

BEGIN apex_util.set_session_lang(:P1_LANGUAGE); END;

Second Action: Submit Page (to refresh the UI with the new language).

Conclusion: Localization is Continuous

Translation is not a one-time task. Every time you add a new page or button, you must repeat the Seed -> Export -> Translate -> Apply -> Publish cycle.

By following this structured approach, you ensure your Oracle APEX application is truly global, providing a native experience for every user regardless of their region.

Frequently Asked Questions (FAQ)

• Do I need to reinstall the language app every time? No, you just need to re-publish the translation mapping after applying new XLIFF files.
• Can I translate Interactive Grid column headers? Yes, the seeding process captures IG headers automatically. For complex data inside the grid, use APEX_LANG.LANG.