TRANSLATETOOLS Package Documentation I18N/L10N

Package: translateTools
Purpose: APEX Translation Management Utilities
Author: Niall McP
Created: August 4, 2025
Generated: August 6, 2025

Package Overview

The translateTools package provides utility functions for managing APEX translations in multi-language applications. It automates the complex process of seeding and publishing translations across multiple workspaces and applications, ensuring consistent internationalization deployment.

Key Features

Requirements & Dependencies

⚠️ Administrative Function

This package contains administrative functions that modify APEX applications and translations. Use with caution in production environments and ensure proper testing in development environments first.

Table of Contents

Translation Procedures

seedAndPublishTranslationsApp

procedure seedAndPublishTranslationsApp ( p_app_id in apex_application_trans_map.primary_application_id%type );

Seeds and publishes all translatable applications in the current schema's workspaces that require synchronization. This is the primary procedure for managing APEX application translations, automating the complex process of translation deployment across multiple languages and workspaces.

Parameter Type Required Description
p_app_id apex_application_trans_map.primary_application_id%type Optional The ID of the primary application to process. If NULL, all applications requiring synchronization will be processed.

Operation Flow

Step 1: Identifies all translation mappings requiring synchronization
Step 2: Loops through each unique workspace and application
Step 3: Sets APEX security group context for each workspace
Step 4: Calls APEX_LANG.SEED_TRANSLATIONS for each translation language
Step 5: Calls APEX_UTIL.PUBLISH_APPLICATION for each translated application
Step 6: Outputs progress messages via DBMS_OUTPUT

Exception Handling

No exceptions are explicitly raised by this procedure. It relies on the underlying APEX_LANG and APEX_UTIL packages to throw errors if operations fail. Monitor DBMS_OUTPUT for success/failure messages during execution.

Modification History

Date Author Description
2025-08-04 Niall McP Initial version

Translation Workflow

APEX Translation Process

Understanding the APEX translation workflow is crucial for effective use of this package:

1. Translation Mapping Setup

Before using this package, translation mappings must be configured in APEX:

  • Primary Application: The source application with default language
  • Translated Applications: Target applications for each supported language
  • Language Codes: ISO language codes (e.g., 'en', 'fr', 'es')
  • Workspace Association: Mapping between applications and workspaces

2. Seeding Process

The seeding process extracts translatable text from the primary application:

  • Text Extraction: Identifies all translatable strings in the application
  • Template Creation: Creates translation templates for each target language
  • Synchronization: Updates existing translations with new/changed text
  • Validation: Ensures translation integrity and completeness

3. Publishing Process

Publishing applies translations and makes them available to users:

  • Translation Application: Applies translated text to target applications
  • Deployment: Makes translated applications available in runtime
  • Cache Refresh: Updates APEX internal caches with new translations
  • Verification: Confirms successful deployment of translations

Internationalization Concepts

Key I18N/L10N Concepts

Internationalization (I18N)

  • Text Externalization: Separating translatable text from application logic
  • Locale Support: Supporting multiple languages and cultural conventions
  • Character Encoding: Proper handling of Unicode and multi-byte characters
  • Resource Management: Organizing and managing translation resources

Localization (L10N)

  • Translation: Converting text to target languages
  • Cultural Adaptation: Adapting content for local cultures
  • Format Localization: Dates, numbers, currencies for local formats
  • Layout Adjustment: Text expansion/contraction considerations

Usage Examples

Processing All Applications

-- Process all applications requiring translation synchronization begin translateTools.seedAndPublishTranslationsApp(p_app_id => null); end; /

This example processes all applications in the current schema's workspaces that have pending translation synchronization requirements.

Processing Specific Application

-- Process translations for a specific application (e.g., App ID 100) begin translateTools.seedAndPublishTranslationsApp(p_app_id => 100); end; /

This example processes translations only for application ID 100, useful when you need to update translations for a specific application after changes.

Monitoring Execution

-- Enable DBMS_OUTPUT to monitor progress set serveroutput on size unlimited begin translateTools.seedAndPublishTranslationsApp(p_app_id => 100); end; / -- Expected output: -- Processing application 100 in workspace WORKSPACE_001 -- Seeding translations for language: fr -- Publishing application 101 (French translation) -- Seeding translations for language: es -- Publishing application 102 (Spanish translation) -- Translation processing completed.

Enable DBMS_OUTPUT to see detailed progress messages during translation processing.

Troubleshooting

Common Issues and Solutions

Insufficient Privileges

Error: ORA-00942: table or view does not exist

Solution: Ensure execute privileges on APEX_UTIL and APEX_LANG packages are granted to the executing schema.

Workspace Context Issues

Error: Application not found or inaccessible

Solution: Verify that the executing user has access to all required APEX workspaces and applications.

Translation Mapping Problems

Error: No translation mappings found

Solution: Ensure translation mappings are properly configured in APEX administration for the target applications.

Memory or Performance Issues

Error: Process takes too long or runs out of memory

Solution: Process applications individually using the p_app_id parameter instead of processing all applications at once.

Best Practices