146 lines
9.6 KiB
XML
146 lines
9.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
|
|
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
|
|
<reference id="plugin-addgeneratedtext">
|
|
<title>Customizing generated text</title>
|
|
<shortdesc>Generated text is the term for strings that are automatically added by the build, such as "Note" before the
|
|
contents of a <xmlelement>note</xmlelement> element.</shortdesc>
|
|
<prolog>
|
|
<metadata>
|
|
<keywords>
|
|
<indexterm><xmlelement>note</xmlelement></indexterm>
|
|
<indexterm><xmlatt>xml:lang</xmlatt></indexterm>
|
|
<indexterm>languages
|
|
<indexterm>adding support for</indexterm></indexterm>
|
|
<indexterm>English</indexterm>
|
|
<indexterm>Icelandic</indexterm>
|
|
<indexterm>Russian</indexterm>
|
|
<indexterm>Vietnamese</indexterm>
|
|
<indexterm>Gaelic</indexterm>
|
|
<indexterm>strings</indexterm>
|
|
<indexterm>generated text</indexterm>
|
|
<indexterm>draft
|
|
<indexterm>localizing generated text</indexterm></indexterm>
|
|
</keywords>
|
|
</metadata>
|
|
</prolog>
|
|
<refbody>
|
|
<section>
|
|
<p>The generated text extension point is used to add new strings to the default set of generated text. There are
|
|
several reasons you may want to use this:
|
|
<ul>
|
|
<li>It can be used to add new text for your own processing extensions; for example, it could be used to add
|
|
localized versions of the string "User response" to aid in rendering troubleshooting information.</li>
|
|
<li>It can be used to override the default strings in the toolkit; for example, it could be used to reset the
|
|
English string "Figure" to "Fig".</li>
|
|
<li>It can be used to add support for new languages (for non-PDF transforms only; PDF requires more
|
|
complicated localization support). For example, it could be used to add support for Vietnamese or Gaelic; it
|
|
could also be used to support a new variant of a previously supported language, such as Australian
|
|
English.</li>
|
|
</ul></p>
|
|
<dl>
|
|
<dlentry>
|
|
<dt><codeph>dita.xsl.strings</codeph></dt>
|
|
<dd>Add new strings to generated text file. </dd>
|
|
</dlentry>
|
|
</dl>
|
|
</section>
|
|
<example>
|
|
<title>Example: adding new strings</title>
|
|
<p>First, copy the file <filepath>xsl/common/strings.xml</filepath> from the base plug-in directory
|
|
<filepath>plugins/org.dita.base</filepath> to your plug-in, and edit it to contain the languages that you are
|
|
providing translations for ("en-US" must be present). For this sample, copy the file into your plug-in as
|
|
<filepath>xsl/my-new-strings.xml</filepath>. The new strings file will look something like this:</p><codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><?xml version="1.0" encoding="utf-8"?>
|
|
<!-- Provide strings for my plug-in; this plug-in supports
|
|
English, Icelandic, and Russian. -->
|
|
<langlist>
|
|
<lang xml:lang="en" filename="mystring-en-us.xml"/>
|
|
<lang xml:lang="en-US" filename="mystring-en-us.xml"/>
|
|
<lang xml:lang="is" filename="mystring-is-is.xml"/>
|
|
<lang xml:lang="is-IS" filename="mystring-is-is.xml"/>
|
|
<lang xml:lang="ru" filename="mystring-ru-ru.xml"/>
|
|
<lang xml:lang="ru-RU" filename="mystring-ru-ru.xml"/>
|
|
</langlist></codeblock>
|
|
<p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</filepath> from the base plug-in directory
|
|
<filepath>plugins/org.dita.base</filepath> to your plug-in, and replace the content with your own strings (be
|
|
sure to give them unique name attributes). Do the same for each language that you are providing a translation
|
|
for. For example, the file <filepath>mystring-en-us.xml</filepath> might contain:</p><codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><?xml version="1.0" encoding="utf-8"?>
|
|
<strings xml:lang="en-US">
|
|
<str name="String1">English generated text</str>
|
|
<str name="Another String">Another String in English</str>
|
|
</strings></codeblock>
|
|
<p>Use the following extension code to include your strings in the set of generated text: </p><codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><plugin id="com.example.strings">
|
|
<feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/>
|
|
</plugin></codeblock>
|
|
<p>The string is now available to the "getVariable" template used in many DITA-OT XSLT files. For example, if
|
|
processing in a context where the xml:lang value is "en-US", the following call would return "Another String in
|
|
English":</p><codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><xsl:call-template name="getVariable">
|
|
<xsl:with-param name="id" select="'Another String'"/>
|
|
</xsl:call-template></codeblock>
|
|
<note>If two plug-ins define the same string, the results will be non-deterministic, so multiple plug-ins should
|
|
not try to create the same generated text string. One common way to avoid this problem is to ensure the name
|
|
attributes used to look up the string value are related to the ID or purpose of your plug-in.</note>
|
|
</example>
|
|
<example>
|
|
<title>Example: modifying existing strings</title>
|
|
<p>The process for modifying existing generated text is exactly the same as for adding new text, except that the
|
|
strings you provide override values that already exist. To begin, set up the
|
|
<filepath>xsl/my-new-strings.xml</filepath> file in your plug-in as in the previous example. </p>
|
|
<p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</filepath> from the base plug-in directory
|
|
<filepath>plugins/org.dita.base</filepath> to your plug-in, and choose the strings you wish to change (be sure
|
|
to leave the name attribute unchanged, because this is the key used to look up the string). Create a strings
|
|
file for each language that needs to modify existing strings. For example, the new file
|
|
<filepath>mystring-en-us.xml</filepath> might contain:</p><codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><?xml version="1.0" encoding="utf-8"?>
|
|
<strings xml:lang="en-US">
|
|
<str name="Figure">Fig</str>
|
|
<str name="Draft comment">ADDRESS THIS DRAFT COMMENT</str>
|
|
</strings></codeblock>
|
|
<p>To include the new strings, use the same method as above to add these strings to your
|
|
<filepath>plugin.xml</filepath> file. Once this plug-in is installed, where XHTML output previously generated
|
|
the term "Figure", it will now generate "Fig"; where it previously generated "Draft comment", it will now
|
|
generate "ADDRESS THIS DRAFT COMMENT". The same strings in other languages will not be modified unless you also
|
|
provide new versions for those languages.</p><note>If two plug-ins override the same string in the same
|
|
language, the results will be non-deterministic (either string may be used under different conditions). Multiple
|
|
plug-ins should not override the same generated text string for a single language.</note>
|
|
</example>
|
|
<example>
|
|
<title>Example: adding a new language</title>
|
|
<p>The process for adding a new language is exactly the same as for adding new text, except you are effectively
|
|
just translating an existing strings file. To begin, set up the <filepath>xsl/my-new-strings.xml</filepath> file
|
|
in your plug-in as in the previous examples. In this case, the only difference is that you are adding a mapping
|
|
to new languages; for example, the following file would be used to set up support for
|
|
Vietnamese:<codeblock
|
|
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
|
|
><?xml version="1.0" encoding="utf-8"?>
|
|
<!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
|
|
to the translations in this plug-in. -->
|
|
<langlist>
|
|
<lang xml:lang="vi" filename="strings-vi.xml"/>
|
|
<lang xml:lang="vi-VN" filename="strings-vi.xml"/>
|
|
</langlist></codeblock></p>
|
|
<p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</filepath> from the base plug-in directory
|
|
<filepath>plugins/org.dita.base</filepath> to your plug-in, and rename it to match the language you wish to
|
|
add. For example, to support Vietnamese strings you may want to pick a name like
|
|
<filepath>strings-vi.xml</filepath>. In that file, change the <xmlatt>xml:lang</xmlatt> attribute on the root
|
|
element to match your new language.</p>
|
|
<p>Once the file is ready, translate the contents of each <xmlelement>str</xmlelement> element (be sure to leave
|
|
the name attribute unchanged). Repeat this process for each new language you wish to add.</p>
|
|
<p>To include the new languages, use the same method as above to add these strings to your
|
|
<filepath>plugin.xml</filepath> file. Once this plug-in is installed, non-PDF builds will include support for
|
|
Vietnamese; instead of generating the English word "Caution", the element <codeph><note type="caution"
|
|
xml:lang="vi"></codeph> may generate something like "<term xml:lang="vi">chú ý</term>".</p><note>If two
|
|
plug-ins add support for the same language using different values, the results will be non-deterministic
|
|
(translations from either plug-in may be picked up under different conditions).</note>
|
|
</example>
|
|
</refbody>
|
|
</reference>
|