CL2 Localization Proposal

No CL2 issue # assigned

Localization Background

• Localization units support companies that provide complex language support.

– Their customers don’t want to take up space for languages they don’t use.– The teams that drive localization decisions can be completely separate from the

teams that drive core content decisions. These decisions can change right up to the last minute and include:

• Which languages will be required vs. optional;

• How language selections are grouped;

• Which languages will be packaged together;

• Which languages will ship with the core content and which will be delivered later.

• Localization units are optional for companies that deliver only required languages.

– Language support can be packaged in the same artifacts as core content and only InstallableUnits used.

– Localization units may provide development efficiencies and be used even in this scenario.

Current SituationCurrent localization function

1. The set of selectable languages is defined for the SDD as a whole. 2. Required languages can be known only by diff’ing the SupportedLanguages

and the SelectableLanguages elements. 3. Localization content for required languages is now under SelectableContent

implying that localization units are only for optional languages. 4. The selection of localization content for deployment is determined entirely by

information within each localization unit, i.e. by the SupportedLanguages and LocalizationBase elements.

Issues1. Sometimes language selection is based on groups of languages. There is no

way to define a group of languages that must be selected together.2. Sometimes the set of required and selectable languages differs per feature.

There is no way to define a different set of supported languages for a feature.3. Sometimes there is a good reason to put even required language support in

localization units. With LocalizationContent currently underneath SelectableContent there is no clear support for this.

4. Encoding selection criteria only in the localization units requires processing every localization unit. The performance of this may be unacceptable.

Localization Proposal Part 1

Specifying Language GroupsAddresses:•Issue 1 – specifying required language•Issue 2 – specifying languages per feature

Modify the SupportedLanguages element of CompositeInstallable to:1. clearly distinguish between base and selectable languages;2. support definition of language groups;3. allow display information to be defined per language group.

The new LanguageGroupType has an id attribute that isused to reference the language group.

The unchanged LanguageSetType is a space-delimited list of locale codes. This allows a language group to contain one language or many languages.

Add an optional SupportedLanguages element to Feature to be used when the Feature needs to override the globally defined set of supported languages.

Use of SupportedLanguages in a Feature is a complete override of the global definition in CompositeInstallable. All Language groups supported by that feature must be specified, not just deltas from the global list.

Implications:

• When defining an SDD with an InstallableUnit at the root (CL1 or CL2) there is no display information available to describe the required languages. When using a CompositeInstallable at the root, display information is available. Is this OK?

• The SupportedLanguages element is currently defined in InstallUnitType which is extended by CompositeInstallableType, InstallableUnitType and LocalizationUnitType. It must be removed from InstallUnitType to support the proposed changes. This means SupportedLanguages in InstallableUnit and LocalizationUnit has to move to a new location within the sequence of child elements. (See CL1 Impact chart at end of deck.)

<sdd-dd:CompositeInstallable id="idvalue0"> <sdd-dd:SupportedLanguages>

<sdd-dd:RequiredLanguages id="FIGS"> <sdd-dd:DisplayName>French, English and German</sdd-dd:DisplayName> <sdd-dd:Description>

French, English and German are always deployed. </sdd-dd:Description> <sdd-dd:Languages>en_fr en_EN en_de</sdd-dd:Languages>

</sdd-dd:RequiredLanguages> <sdd-dd:OptionalLanguages>

<sdd-dd:LanguageGroup id="Japanese"> <sdd-dd:DisplayName>Japanese</sdd-dd:DisplayName> <sdd-dd:Languages>en_ja</sdd-dd:Languages>

</sdd-dd:LanguageGroup> <sdd-dd:LanguageGroup id="EasternEuropeanLanguages">

<sdd-dd:DisplayName>Eastern European Languages</sdd-dd:DisplayName> <sdd-dd:Description>Polish, Hungarian, Croatian and Czech</sdd-dd:Description> <sdd-dd:Languages>en_pl en_hu en_hr en_cs</sdd-dd:Languages>

</sdd-dd:LanguageGroup> </sdd-dd:OptionalLanguages>

</sdd-dd:SupportedLanguages>

Example definition of SupportedLanguages

Localization Proposal Part 2

Determining which Localization Content is “in scope”

Addresses Issue 4 - Performance

Determining that a localization unit is “in scope”.

• Currently: every localization unit had to be processed to determine if one of its supported languages was in scope and if its localization base identified a resource that was in scope.

• Proposal: select localization units by references in the base and selectable content trees. Reduce use of localization base.– This is similar to how features define references to content selected by

the feature.– Organize those references within the content hierarchy by language

group, allowing parsing of only localization units that are known to be in scope. Instead, parse the new references trees and then parse the localization units just enough to select by id.

– Document that localization base should not be defined by localization units which localize content carried in the same SDD. This information is now carried in the content hierarchy via the references to localization units.

– This trades a more complex tree for presumably higher-performance processing.

The base content hierarchy identifies by reference the localization content that localize the base content.

Features identify by reference the localization content that localizes selectable content associated with the feature.

Localization references are organized by language group.

The languageGroupRef attribute of the ByLanguageGroup element identifies the language group –from the defining feature’s SupportedLanguages, if any, or from the globally defined SupportedLanguages.

Is an adjective phrase OK for this name? It is the most understandable name I could come up with and I think it works well even though it isn’t the usual noun.

Example definition of localization references.

<sdd-dd:LocalizationReferences> <sdd-dd:ByLanguageGroup languageGroupRef="FIGS">

<sdd-dd:ContentRef>FIGSSupportForBaseContent</sdd-dd:ContentRef> </sdd-dd:ByLanguageGroup> <sdd-dd:ByLanguageGroup languageGroupRef="Japanese">

<sdd-dd:ContentRef>JapaneseSupportForBaseContent</sdd-dd:ContentRef> </sdd-dd:ByLanguageGroup></sdd-dd:LocalizationReferences>

Potential Localization Processing Logic

For all scenarios1. Determine language groups that are “in scope”.2. Look in BaseContent at the localization references for each

language group that is “in scope”. Look in the LocalizationContent elements in the base tree - at the root or under any CompositeUnit - and put LocalizationUnits and language packs that are referenced “in scope”.

3. Look in each selected feature at the localization references for language groups that are “in scope”. Look in the LocalizationContent elements in the SelectableContent tree – at the root or under any CompositeUnit – and put LocalizationUnits and language packs that are referenced “in scope”.

4. As with all content units, evaluate the Condition element, if any. If a LocalizationBase is defined evaluate it. (Only LocalizationUnits that are not associated with content in the SDD should have LocalizationBase defined.)

Localization Proposal Part 3

Defining Localization ContentAddresses Issue 3 – sensible placement of localization content

Placing localization units in the content hierarchy.

• Currently: a single LocalizationContent tree under SelectableContent contains all localization units.

• Keep in mind: business decisions driving organization of localization content may be completely independent of decisions driving organization of core content. A single localization unit or package could potentially contain support

• for both required and optional languages• for both base and selectable content

• Proposal: localization units that localize base content are defined in the base content tree. Localization units that localize selectable content are defined in the selectable content tree. This puts the localization units in the same part of the content tree where they are referenced. (But does not address the fact that a localization unit could potentially localize both base and selectable content.)

Add LocalizationContent to ContentListGroup allowing localization to be defined directly under base and selectable content or under CompositeUnits. All localization units and referenced language packs are put under a LocalizationContent element somewhere in the hierarchy. Nothing in a LocalizationContent element is in scope unless it’s reference is in scope.

Localization Proposal Part 4

Related clean-up

Add Completion element to Localization Unit

The same forces that result in an InstallableUnit or ConfigurationUnit requiring a completion action could result in a LocalizationUnit requiring a completion action. Add one in the same order as it appears in an InstallableUnit.

Update package type enumeration

• Currently: the value “modification” is intended to cover language packs as well as functional additions or changes.

• Currently and with Proposal: The SDD contains a very specific element in LocalizationContent for aggregating SDDs with only localization content, (yet the current package type enumeration is not specific enough to identify that package as appropriate for use in this element).– Current element name: ReferencedPackage– Proposed element name: ContainedLanguagePack

• Proposal: Add the enumeration value “languagePack” or “localizationPackage” to the package type enumerations. Modify the name of the related element, if necessary, to match.

CL1 Impacts

• Syntax Only Impact: The SupportedLanguages element in InstallableUnit and LocalizationUnit has to move to a new location within the sequence of child elements in order to change the SupportedLanguages type in CompositeInstallable. Any CL1 SDD that uses SupportedLanguages and the elements between the old and new location will have to perform a straight-forward migration.

• Potential Minor Semantic Impact: The package type enumeration contains a new value, “languagePack”. If a CL1 SDD uses the package type “modification” to mean “languagePack”, the value may need to be changed.