Oracle constructs that support XML translation are described. They are deprecated starting with Oracle Database 12c Release 1 (12.1.0.1).
You can use the deprecated Oracle support for XML translation to translate strings contained in XMLType
documents in Oracle XML DB Repository into various (natural) languages.
You can store XML documents in Oracle XML DB Repository as XMLType
instances. These documents sometimes contain strings that must be translated into various (natural) languages. To use the deprecated Oracle XML translation support, you store both the original strings and their translations in the repository. You can then retrieve and operate on these strings, depending on your language settings.
Note:
XML schemas stored object-relationally are not translatable.
You must make certain changes to an XML schema and any associated XML instance documents, to make the documents translatable.
Attribute xdb:translate
must be specified in an XML schema for each element that is to be translated. Some restrictions apply to attribute xdb:translate
. During XML schema registration, PL/SQL procedure DBMS_XMLSCHEMA.registerSchema
checks whether the XML schema satisfies these restrictions.
Attribute xdb:translate
can be specified only on complexType
elements that have simpleContent
. Here, simpleContent
must be an extension or a restriction of type string
. However, if a complexType
element has the xdb:translate
flag set, then none of its descendants can have this flag set.
Attribute xdb:translate
can be set only on a single-valued element, which has exactly one translation. For such an element, the value of xdb:maxOccurs
must be 0
or 1
. If you want to set this attribute on a multiple-valued element, the element must have an ID
attribute, which uniquely identifies the element.
Support for translation language attributes xml:lang
and xdb:srclang
is described.
xml:lang
: For an instance document associated with an XML schema that supports translations, you must specify the translation language. You can do this by annotating each translation with attribute xml:lang
. The allowed values of the xml:lang
attribute are the language identifiers identified by IETF RFC 3066.
xdb:srclang
: For multiple-valued elements, that is, elements that can have multiple translations, only one translation can be used as the source language translation. That translation is specified by attribute xdb:srclang
. This is the default translation, which is returned when the session language is not specified.
You can use deprecated translation-specifying XML Schema attributes to make elements in a sample document translatable.
Example D-1 shows an XML schema that defines documents that contain a title string that needs to be translatable.
Example D-2 shows a document that is associated with the XML schema of Example D-1.
To make the top-level title translatable, set xdb:translate
to true
. This is a single-valued element (xdb:maxOccurs
is 1
). Example D-3 shows the new XML schema, where attribute xdb:translate
is true
.
Example D-4 shows an instance document after translation of the title text.
To make the title translatable in the case of a multi-valued element, you would set xdb:maxOccurs
to unbounded
. However, xdb:translate
cannot be set to true
for a multiple-valued element, unless there is an identifier attribute that uniquely identifies each element. Example D-5 shows an XML schema that uses an identifier attribute id
for the title
element.
Example D-6 shows a document associated with the XML schema in Example D-5.
Example D-1 XML Schema Defining Documents with a Title To Be Translated
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xdbsc="http://xmlns.oracle.com/xdb/security.xsd"
xmlns:xdb="http://xmlns.oracle.com/xdb.xsd"
targetNamespace="http://xmlns.oracle.com/xdb/security.xsd"
elementFormDefault="qualified" version="1.0">
<annotation>
<documentation>
This XML schema describes the structure of Security Class documents.
</documentation>
</annotation>
<element name="securityClass" xdb:defaultTable="">
<complexType>
<sequence>
<element name="name" type="string"/>
<element name="title" minOccurs="0" maxOccurs="unbounded"/>
<element name="inherits-from" type="QName" minOccurs="0" maxOccurs="unbounded"/>
<element name="privlist" minOccurs="0" maxOccurs="unbounded">
<complexType>
<choice minOccurs="0" maxOccurs="unbounded">
<element ref="xdbsc:privilege"/>
<element ref="xdbsc:aggregatePrivilege"/>
</choice>
</complexType>
</element>
<!-- this "any" contains all application specific information
for a security class in general e.g. reason for creation -->
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="targetNamespace" type="anyURI" use="required"/>
<!-- all privileges in this security class are under this target namespace -->
</complexType>
</element>
<element name="aggregatePrivilege">
<complexType>
<sequence>
<element name="title" minOccurs="0" maxOccurs="unbounded"/>
<sequence maxOccurs="unbounded">
<element name="privilegeRef">
<complexType>
<attribute name="name" type="QName" use="required"/>
</complexType>
</element>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<!-- this "any" contains all application specific information
an aggregate privilege e.g. translations -->
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="name" type="string" use="required"/>
</complexType>
</element>
<element name="privilege">
<complexType>
<sequence minOccurs="0">
<element name="title" minOccurs="0" maxOccurs="unbounded"/>
<sequence minOccurs="0" maxOccurs="unbounded">
<element name="columnRef">
<complexType>
<attribute name="schema" type="string" use="required"/>
<attribute name="table" type="string" use="required"/>
<attribute name="column" type="string" use="required"/>
</complexType>
</element>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<!-- this "any" contains all application specific information
for a privilege e.g. translations -->
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="name" type="string" use="required"/>
</complexType>
</element>
</schema>
Example D-2 Untranslated Instance Document
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title> Security Class Example </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> <privlist> <privilege name="privilege1"/> <aggregatePrivilege name="iStorePOApprover"> <title> iStore Purchase Order Approver </title> <privilegeRef name="is:privilege1"/> <privilegeRef name="oa:submitPO"/> <privilegeRef name="oa:privilege3"/> </aggregatePrivilege> <privilege name="privilege2"> <title> secondary privilege </title> <columnRef schema="APPS" table="PurchaseOrder" column="POId"/> <columnRef schema="APPS" table="PurchaseOrder" column="Amount"/> </privilege> </privlist> </securityClass>
Example D-3 XML Schema with Attribute xdb:translate for a Single-Valued Element
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xdbsc="http://xmlns.oracle.com/xdb/security.xsd" xmlns:xdb="http://xmlns.oracle.com/xdb.xsd" targetNamespace="http://xmlns.oracle.com/xdb/security.xsd" elementFormDefault="qualified" version="1.0"> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/> <xs:import namespace-"http://xmlns.oracle.com/xdb" schemaLocation="http://xmlns.oracle.com/xdb/xmltr.xsd"/> <annotation> <documentation> This XML schema describes the structure of Security Class documents. </documentation> </annotation> <element name="securityClass" xdb:defaultTable=""> <complexType> <sequence> <element name="name" type="string"/> <element ref="titleref" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="1" xdb:translate="true"/> <element name="inherits-from" type="QName" minOccurs="0" maxOccurs="unbounded"/> <element name="privlist" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="1"> <complexType> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="xdbsc:privilege"/> <element ref="xdbsc:aggregatePrivilege"/> </choice> </complexType> </element> <!-- this "any" contains all application specific information for a security class in general e.g. reason for creation --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="targetNamespace" type="anyURI" use="required"/> <!-- all privileges in this security class are under this target namespace --> </complexType> </element> <element name="aggregatePrivilege"> <complexType> <sequence> <element name="title" minOccurs="0" maxOccurs="unbounded"/> <sequence maxOccurs="unbounded"> <element name="privilegeRef"> <complexType> <attribute name="name" type="QName" use="required"/> </complexType> </element> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <!-- this "any" contains all application specific information an aggregate privilege e.g. translations --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="name" type="string" use="required"/> </complexType> </element> <element name="privilege"> <complexType> <sequence minOccurs="0"> <element name="title" minOccurs="0" maxOccurs="unbounded"/> <sequence minOccurs="0" maxOccurs="unbounded"> <element name="columnRef"> <complexType> <attribute name="schema" type="string" use="required"/> <attribute name="table" type="string" use="required"/> <attribute name="column" type="string" use="required"/> </complexType> </element> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <!-- this "any" contains all application specific information for a privilege e.g. translations --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="name" type="string" use="required"/> </complexType> </element> <element name="titleref"> <complexType> <simpleContent> <extension base="xs:string"> <attribute ref="xml:lang"/> <attribute ref="xdb:srclang"/> </extension> </simpleContent> </complexType> </element> </schema>
Example D-4 Translated Document
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps"> <name> securityClassExample </name> <title xdb:srclang="true"> Security Class Example </title> <title> Security Class Example - Spanish </title> <title> Security Class Example - French </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> <privlist> <privilege name="privilege1"/> <aggregatePrivilege name="iStorePOApprover"> <title> iStore Purchase Order Approver </title> <privilegeRef name="is:privilege1"/> <privilegeRef name="oa:submitPO"/> <privilegeRef name="oa:privilege3"/> </aggregatePrivilege> <privilege name="privilege2"> <title> secondary privilege </title> <columnRef schema="APPS" table="PurchaseOrder" column="POId"/> <columnRef schema="APPS" table="PurchaseOrder" column="Amount"/> </privilege> </privlist> </securityClass>
Example D-5 XML Schema with Attribute xdb:translate for a Multi-Valued Element
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xdbsc="http://xmlns.oracle.com/xdb/security.xsd" xmlns:xdb="http://xmlns.oracle.com/xdb.xsd" targetNamespace="http://xmlns.oracle.com/xdb/security.xsd" elementFormDefault="qualified" version="1.0"> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/> <xs:import namespace-"http://xmlns.oracle.com/xdb" schemaLocation="http://xmlns.oracle.com/xdb/xmltr.xsd"/> <annotation> <documentation> This XML schema describes the structure of Security Class documents. </documentation> </annotation> <element name="securityClass" xdb:defaultTable=""> <complexType> <sequence> <element name="name" type="string"/> <element name="title" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="1"/> <element name="inherits-from" type="QName" minOccurs="0" maxOccurs="unbounded"/> <element name="privlist" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="1"> <complexType> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="xdbsc:privilege"/> <element ref="xdbsc:aggregatePrivilege"/> </choice> </complexType> </element> <!-- this "any" contains all application specific information for a security class in general e.g. reason for creation --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="targetNamespace" type="anyURI" use="required"/> <!-- all privileges in this security class are under this target namespace --> </complexType> </element> <element name="aggregatePrivilege"> <complexType> <sequence> <element name="titleref" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="unbounded" xdb:translate="true"/> <sequence maxOccurs="unbounded"> <element name="privilegeRef"> <complexType> <attribute name="name" type="QName" use="required"/> </complexType> </element> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <!-- this "any" contains all application specific information an aggregate privilege e.g. translations --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="name" type="string" use="required"/> </complexType> </element> <element name="privilege"> <complexType> <sequence minOccurs="0"> <element name="titleref" minOccurs="0" maxOccurs="unbounded" xdb:maxOccurs="unbounded" xdb:translate="true"/> <sequence minOccurs="0" maxOccurs="unbounded"> <element name="columnRef"> <complexType> <attribute name="schema" type="string" use="required"/> <attribute name="table" type="string" use="required"/> <attribute name="column" type="string" use="required"/> </complexType> </element> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <!-- this "any" contains all application specific information for a privilege e.g. translations --> <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="name" type="string" use="required"/> </complexType> </element> <element name="titleref"> <complexType> <simpleContent> <extension base="xs:string"> <attribute ref="xml:lang"/> <attribute ref="xdb:srclang"/> <attribute name="id" type="integer"/> </extension> </simpleContent> </complexType> </element> </schema>
Example D-6 Translated Document for an XML Schema with Multiple-Valued Elements
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps"> <name> securityClassExample </name> <title> Security Class Example </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> <privlist> <privilege name="privilege1"/> <aggregatePrivilege name="iStorePOApprover"> <title> iStore Purchase Order Approver </title> <privilegeRef name="is:privilege1"/> <privilegeRef name="oa:submitPO"/> <privilegeRef name="oa:privilege3"/> </aggregatePrivilege> <privilege name="privilege2"> <title id="2" xdb:srclang="true"> secondary privilege - english </title> <title id="1"> primary privilege - french </title> <title id="1" xdb:srclang="true"> primary privilege - english </title> <columnRef schema="APPS" table="PurchaseOrder" column="POId"/> <columnRef schema="APPS" table="PurchaseOrder" column="Amount"/> </privilege> </privlist> </securityClass>
You can perform insert, query, and update operations on translated documents. Examples are shown of inserting a document with and without language information.
Insert: You can insert a document into Oracle XML DB, if it conforms to an XML schema that supports translations. For the document that contains translations, you can either provide the language information or use the session language translation.
When the document does not contain the language information and the xml:lang
attribute is not set, the session language is used for translation. Example D-7 describes a document with a session language of Japanese. Attribute xml:lang
is set to session language
, and attribute xdb:srclang
is set to true
.
Example D-8 shows the document after it is inserted into Oracle XML DB Repository.
When you provide the language information, you set attribute xml:lang
by either explicitly marking a translation as xdb:srclang=true
or using the session language translation in attribute xdb:srclang
. If you do neither, then an arbitrary translation is picked, for which xdb:srclang
is set to true
.
Example D-9 describes a document with a session language of Japanese.
Example D-10 shows the document after it is inserted into Oracle XML DB Repository.
Query: If you query nodes that involve translated elements, the query displays the translation's default behavior. In order to specify that the translation's default behavior should be applied to the query result, you need to use the Oracle XPath function ora:translate
. This is the syntax of the function:
Nodeset ora:translate(Nodeset parent, String childname, String childnsp)
Parameter parent
is the parent node under which you want to search for the translated nodes; childname
is the name of the child node; and childnsp
is the namespace URL of the child node.
Function ora:translate
returns a positive integer when the name of the parent node matches the name of the specified child node, and the xml:lang
value is same as the session language or the language for which xdb:srclang
is true
.
When SQL functions such as XMLQuery
are applied to translated documents, they return the session language translation, if present, or the source language translation, otherwise. For example, this query returns the session language translation:
SELECT XMLQuery('$x/ora:translate(securityClass, "title")' PASSING x.OBJECT_VALUE AS "x" RETURNING CONTENT) FROM some_table x;
This is the output of that query:
<title> Security Class Example - FR </title>
To obtain the result in a particular language, specify it in the XPath expression.
SELECT XMLQuery('$x/securityClass/title[@xml:lang="en"]' PASSING x.OBJECT_VALUE AS "x" RETURNING CONTENT) FROM some_table x;
This is the output of that query:
<title xdb:srclang="true"> Security Class Example </title>
Because you can store translated documents only as text (CLOB
) or binary XML, only functional evaluation and queries with a function-based index, an XMLIndex
index, or a CONTEXT
index are possible. For XMLIndex
index and CONTEXT
index queries, if the document has a session language translation, then that is returned, otherwise the source language translation is returned. However, for queries with a function-based index, you need to create an index with an explicit xml:lang
predicate for every language for which you want to use the index.
When you retrieve the complete document using SQL function XMLSerialize
and PL/SQL constructor XDBURIType
, only the translations that match the session language translations are returned. For protocols, you can set your language preferences, and the document is returned in that language only.
The following PL/SQL procedures and functions support XML translations:
DBMS_XMLTRANSLATIONS.translateXML
: Translate a document to the specified language. If the specified language translation is present, it is returned, otherwise, the source language translation is returned.
For example, if you write translateXML(doc, 'fr')
to specify French as the translation language for the Example D-10, it returns the following code and ignores all other translations:
securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title> Security Class Example - FR </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> </securityClass>
DBMS_XMLTRANSLATIONS.enableTranslation
, DBMS_XMLTRANSLATIONS.disableTranslation
: Enable or disable translations at the session level. Queries work on the base document if the translation is disabled and on the translated document if it is enabled.
DBMS_XMLTRANSLATIONS.getBaseDocument
: Returns the entire document, with all of the translations.
Update: You can use Oracle SQL function XMLQuery
together with XQuery Update to update the translated nodes. However, an error is raised if you try to update a translated node without specifying the translation language. The following PL/SQL procedures support update operations on translated documents:
DBMS_XMLTRANSLATIONS.updateTranslation
: This function updates the translation at a specified xpath
in a particular language. If the translation in a particular language is not present, then it is inserted.
DBMS_XMLTRANSLATIONS.setSourceLang
: This procedure sets the source language at a specified xpath to the specified language.
Example D-7 Inserting a Document with No Language Information
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title> Security Class Example </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> </securityClass>
Example D-8 Document After Insertion into the Repository
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title xdb:srclang="true"> Security Class Example </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> </securityClass>
Example D-9 Inserting a Document with Language Information
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title xml:lang="en"> Security Class Example </title> <title xml:lang="fr"> Security Class Example - FR </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> </securityClass>
Example D-10 Document After Insertion
<securityClass xmlns="http://xmlns.oracle.com/xdb/security.xsd" xmlns:is="xmlns.oracle.com/iStore" xmlns:oa="xmlns.oracle.com/OracleApps" targetNamespace="xmlns.oracle.com/example"> <name> securityClassExample </name> <title xml:lang="en" xdb:srclang="true"> Security Class Example </title> <title xml:lang="fr"> Security Class Example - FR </title> <inherits-from>is:iStorePurchaseOrder</inherits-from> </securityClass>
Oracle XML DB provides translation support through the DBMS_XMLTRANSLATIONS
package, which provides an interface to perform translations so that strings can be searched or displayed in various languages. This feature is deprecated.
See Also:
XML Schema Storage and Query: Basic for an overview of XML translations
Deprecated PL/SQL package DBMS_XMLTRANSLATIONS
provides the following methods: updateTranslation
, setSourceLang
, translateXML
, getBaseDocument
, extractXLiff
, mergeXLiff
, disableTranslation
, and enableTranslation
.
updateTranslation()
: Updates the translation in a particular language at the specified XPATH
. If the translation in that language is not present, then it is inserted.
setSourceLang()
: Sets the source language to a particular language at the specified XPATH
.
translateXML()
: Returns the document in the specified language.
getBaseDocument()
: Returns the base document with all the translations.
extractXLiff()
: Extracts the translations in XLIFF
format from either an XMLTYPE
instance or a resource in Oracle XML DB Repository.
mergeXLiff
: Merges the translations in XLIFF
format into either an XMLTYPE
or a resource in Oracle XML DB Repository.
disableTranslation
: Disables translations in the current session so that query or retrieval takes place on the base document, ignoring session language values.
enableTranslation
: Enables translations in the current session.
See Also:
Oracle Database PL/SQL Packages and Type References for a description of the individual DBMS_XMLTRANSLATIONS
methods.