2026年6月22日月曜日

APEXlang形式のエクスポート・ファイルに含まれる日本語について

Oracle APEX 26.1ではエクスポート・フォーマットとしてAPEXlangが採用されています。それまでもYAML形式などでエクスポートはできましたがインポートはできなかったため、出力されたファイルを積極的に読んだり、Gitで管理する（Gitに置くだけではなく、差分やマージを行う）ことは行われていなかったと思います。

APEXlang形式のファイルを扱っていて、ファイルに含まれる日本語について気になった点を記述します。APEXlangでのエクスポートやアプリケーションの翻訳を行わない場合は、あまり意識する必要はないでしょう。

APEXlangについては、以下のAPI Referenceを参照します。


アプリケーションの名前と別名



アプリケーション・ビルダーを使ってAPEXアプリケーションを作成する際に、アプリケーションの名前を日本語にします。通常、意識せずにアプリケーションの名前は日本語にしていると思います。


作成されたアプリケーションの名前とアプリケーション別名に、作成時に指定したアプリケーションの名前が使用されます。（この他にもユーザー・インターフェースのロゴ、ホーム・ページのブレッドクラムの名前、ログイン・ページのリージョンの名前などにも反映されます）。


この部分のAPEXlangでの出力は以下でした。
app 世界食堂 (
    name: 世界食堂
    logo {
        type: text
        text: 世界食堂
    }
日本語のアプリケーション別名がappに続く識別子になっています。アプリケーションの名前も本来、翻訳の対象とはならないため、日本語では無い方が望ましいと思います。

SQLclでapex exportを実行すると、アプリケーション別名が出力フォルダ名になるため、アプリケーション別名が日本語だと、日本語のフォルダが作成されます。フォルダ名が日本語だと、Gitで管理する上でも望ましく無いでしょう。

SQL> apex export -api 105 -exptype apexlang

ワークスペースAPEXDEVをエクスポートしています - アプリケーション105:世界食堂

ファイル世界食堂/application.apxが作成されました


SQL> !ls

世界食堂


SQL> 


APEX 26.1以前でも、簡易URL（friendly URLs）が有効な場合、URLにアプリケーション別名が現れます。そのため、日本語のアプリケーション別名は（アクセスできないわけでは無いが）、避けるべきでした。


上記より、APEXアプリケーションを作成したら、すぐにアプリケーション別名は英数字（およびURLに含めることが許される一部の記号）による識別子として設定すべきです。


アプリケーション別名を変更すると、エクスポートされるフォルダ名およびURLに含まれる文字列は、英数字の識別名に変わります。

SQL> apex export -api 105 -exptype apexlang

ワークスペースAPEXDEVをエクスポートしています - アプリケーション105:世界食堂

ファイルworld-diner/application.apxが作成されました


SQL> !ls

world-diner

世界食堂


SQL> 


ビューAPEX_APPLICATIONSの列ALIASおよびAPEXlangの出力では、アプリケーション別名は英大文字ですが、フォルダ名やURLとなる文字列は英子文字になります。

SQL> select application_name, alias from apex_applications;


APPLICATION_NAME    ALIAS          

___________________ ______________ 

世界食堂                WORLD-DINER    


SQL>


APEXlangのリファレンスのappの項目を見ると、appに続く名前とは別にaliasが必須プロパティとなっていますが、APEX 26.1での出力はそのようになっていません。

アプリケーション別名の変更はプロパティの変更ではなく、識別子の変更にあたります。識別子の変更は、Gitなどでアプリケーションを管理している場合は影響が大きいです。アプリケーションの名前はアプリケーションのプロパティのひとつという扱いで、翻訳の対象ではありません。


ページの名前と別名



新規にページを作成する際に、ページ定義の名前は日本語にすると思います。以下ではページの名前をダッシュボードとしています。


作成されたページでは、名前はダッシュボード、別名はダッシュボード、タイトルもダッシュボードになります。


APEXlang形式でエクスポートすると、ファイル名にp00002-ダッシュボード.apxのように日本語が含まれ、プロパティname、alias、titleが日本語になります。
page 2 (
    name: ダッシュボード
    alias: ダッシュボード
    title: ダッシュボード
    appearance {
        pageTemplate: @/standard
        templateOptions: #DEFAULT#
    }
名前をDashboard、別名をDASHに変更します（別名をDASHBOARDにするとファイル名にどちらが採用されている分からないので、あえて名前と別名を変えています）。タイトルはページに表示される文字列で、アプリケーションの翻訳を行わない限り変更する必要はありません。


APEXlang形式の出力ファイルの名前はページの別名が使用され、p00002-dash.apxでした。ページの内容は以下のように変更されています。
page 2 (
    name: Dashboard
    alias: DASH
    title: ダッシュボード
    appearance {
        pageTemplate: @/standard
        templateOptions: #DEFAULT#
    }
ビューAPEX_APPLICATION_PAGESの列PAGE_ALIASを確認すると、別名は英大文字で保存されていますが、ファイル名およびURLに現れる文字列ともに英子文字になります。


ページの識別子はページ番号なので（API Referenceのpage参照）、ページ番号が変わらなければ同じページですが、ページの別名が変わると出力ファイルが変わります。結果として差分やマージが困難になります。ページの名前はページのプロパティのひとつですが、これも翻訳対象ではありません。


リージョンの名前と静的ID



リージョンの名前とタイトルは、ページ・デザイナではリージョンを作成した後にそれぞれ設定します。タイトルを設定していないとリージョンの名前がページに表示されるため、以前からのAPEX開発者であれば、リージョンにタイトルを設定せず名前をそのまま使用している場合も多いでしょう。


APEX 26.1ではAPEXlangのサポートの関係で、それまでの詳細の静的IDをHTML DOM IDという名称に変更し、新たに静的IDをプロパティとして加えています。

静的IDはリージョンの新規作成時に設定した名前から決まります。上記の例であれば、リージョンの名前をMENUとしているため、静的IDはmenuとなっています。

一度設定されたリージョンの静的IDはロック（変更禁止）され、リージョンの名前を変更しても静的IDは変更されません。


静的IDを変更するには、最初にロックを解除する必要があります。


APEXlang形式の出力を意識せず、APEX 26.1以前と同じようにリージョンの名前に日本語（ここではメニュー）を使用し、タイトルを空白としてリージョンを作成したとします。


この場合、静的IDは日本語のメニューになります（リージョンの新規作成後、編集するページを切り替えるまでは静的IDはロックされません）。


APEXlangでの出力は以下になります。静的IDがリージョンの識別子であるため、日本語が識別子に採用されます。
    region メニュー (
        name: メニュー
        type: classicReport
        source {
            location: localDatabase
            tableName: WR_MENUS_VL
        }
リージョンの識別子を後から変更すると、別のリージョンという扱いになります。そのため、リージョンの新規作成時には、設定される静的IDに注意する必要があります。


ウィザードが割り当てるデフォルトの識別子について



アプリケーション・ビルダーを日本語で使用していると、アプリケーション作成ウィザードやページ作成ウィザードいった、APEXのウィザードが生成するページやコンポーネントの識別子が日本語になっているものがあります。

例えば認証スキームのOracle APEXアカウントは、名前が識別子となるためAPEXlangにそのまま出力されます。


APEXlangでの出力は以下になります。authenticationの識別子に日本語が含まれます。
authentication oracle-apexアカウント (
    name: Oracle APEXアカウント
    type: oracleApexAccounts
)
リストの出力例です。
list ナビゲーション-バー (
    name: ナビゲーション・バー

    entry app-user (
        label: &APP_USER.
        icon {
            imageIconCssClasses: fa-user
        }
        layout {
            sequence: 10
        }
        link {
            target: {
                type: url
                url: #
            }
        }
        userDefinedAttributes {
            2: has-username
        }
    )

    entry list_item (
        label: ---
        layout {
            sequence: 20
            parentEntry: @app-user
        }
        link {
            target: {
                type: url
                url: separator
            }
        }
        serverSideCondition {
            type: userIsAuthenticated
        }
    )

    entry サインアウト (
        label: &{サインアウト}.
        icon {
            imageIconCssClasses: fa-sign-out
        }
        layout {
            sequence: 30
            parentEntry: @app-user
        }
        link {
            target: {
                type: url
                url: &LOGOUT_URL.
            }
        }
        serverSideCondition {
            type: userIsAuthenticated
        }
    )

)

list ナビゲーション-メニュー (
    name: ナビゲーション・メニュー

    entry ホーム (
        label: &{ホーム}.
        icon {
            imageIconCssClasses: fa-home
        }
        layout {
            sequence: 10
        }
        link {
            target: {
                page: 1
            }
        }
    )

)
アプリケーション作成ウィザードの機能や、ページ作成ウィザードの機能で追加したページも、ページ名やページに含まれるリージョンの静的IDは日本語になります。


ページの名前、別名、タイトルともに日本語になります。


リージョンの名前や静的IDも日本語になります。


APEXlang形式のファイルをGitで管理したりテキスト・メッセージベースの翻訳を検討する場合は、これらの標準コンポーネントについても対応を検討する必要があるでしょう。

今回の記事は以上になります。

完
投稿者 時刻:
ラベル: , ,