Projects‎ > ‎XBL‎ > ‎

XBL Internationalization

Note: This page describes an Orbeon Forms project, not a feature which is currently part of Orbeon Forms.

Goals

Provide a mechanism that can be used:
  • By XBL component authors to:
    • Provide localized resources in several languages.
    • Know what is the current language, to select the appropriate resource.
  • By XForms authors to:
    • Set the current language.
    • Override existing resources or add new resources for a new language for existing XBL components.

Implementation

How it can work:
  • Getting the current language
    • Using a well-known property: xxforms:property('oxf.fr.language')
  • Setting the language
    • Globally, by setting the property in properties-local.xml
    • For a given scope, using xxforms:override-property('oxf.fr.language', 'document', 'fr')
    • The scope can be: application, session, document, or request
  • Defining resources
    • The XBL authors declares a static, shared XML instance with the resources
    • The instance follows the same convention we use in Form Runner / Form Builder
  • Getting the value of a resource
    • Common to option A and B:
      • Resources can be overridden by users of components by defining properties, such as (for English): oxf.fr.resource.fr.dialog-select.en.components.labels.open-section
    • Option A: with a function
      • Using xxforms:effective-resource('oxf:/...', 'fr.dialog-select')
      • The first parameter is URL of the resource file for the component, the second is the prefix used when overriding resources for this component
      • The component declares a variable storing the result from a call to xxforms:effective-resource() and uses this variable whenever it needs to get a resource.
    • Option B: with a service
      • Form Runner provides a service: /fr/service/i18n?prefix=fr.dialog-select
      • A new event xxforms-property-change is dispatched by the XForms engine when a property is change
      • This event adds the following 2 event context properties: xxforms-property-name and xxforms-property-value
      • Component authors listens to xxforms-property-change and upon noticing that the property oxf.fr.language or oxf.fr.resource.fr.dialog-select.* changed, they can call the service again to get an updated copy of the current resources.
What it takes to implement this:
  • Common to options A and B:
    • Have hash maps for properties defined at the application, session, document, and request levels.
    • Implement xxforms:override-property('oxf.fr.language', 'document', 'fr') which sets the value of a property in the hash map in the appropriate scope.
    • Implement xxforms:property('oxf.fr.language') to lookup the value a property, looking in sequence to the request, document, session, application scopes, and if it can't find any properties there to the globally defined properties.
  • With option A:
    • Implement xxforms:effective-resource('oxf:/...', 'fr:dialog-select'). A straightforward implementation can be done at first; ultimately, it could return dependency information.
  • With option B:
    • Implement a service /fr/service/i18n?prefix=fr.dialog-select
    • Implement a new event xxforms-property-change when a value is a hash map relevant to the current document is set.

Open questions and downsides:
  • Do we want to use the existing property system to define the current language, the current date format... or do we want a new system?
  • Is xxforms:override-property() enough? What about properties we would need to override before the XForms authors has a chance to run XPath?
  • The syntax for xxforms:resource-value() is rather long; how can we improve this, define a shortcut?
  • Are we happy with the format of the property name used to override resources? We loose the ability to override by app/form, and there will often be a "fr" twice in the name (if now 3 times).


Comments