se/SE/stuff/dita-ot-3.3.3/docsrc/topics/plugin-addgeneratedtext.dita

<?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" xml:lang="en-US">
  <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> 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">&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!-- Provide strings for my plug-in; this plug-in supports
     English, Icelandic, and Russian. -->
&lt;langlist>
  &lt;lang xml:lang="en"     filename="mystring-en-us.xml"/>
  &lt;lang xml:lang="en-US"  filename="mystring-en-us.xml"/>
  &lt;lang xml:lang="is"     filename="mystring-is-is.xml"/>
  &lt;lang xml:lang="is-IS"  filename="mystring-is-is.xml"/>
  &lt;lang xml:lang="ru"     filename="mystring-ru-ru.xml"/>
  &lt;lang xml:lang="ru-RU"  filename="mystring-ru-ru.xml"/>
&lt;/langlist></codeblock>
      <p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</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">&lt;?xml version="1.0" encoding="utf-8"?>
&lt;strings xml:lang="en-US">
  &lt;str name="String1">English generated text&lt;/str>
  &lt;str name="Another String">Another String in English&lt;/str>
&lt;/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">&lt;plugin id="com.example.strings">
  &lt;feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/>
&lt;/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">&lt;xsl:call-template name="getVariable">
  &lt;xsl:with-param name="id" select="'Another String'"/>
&lt;/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> 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">&lt;?xml version="1.0" encoding="utf-8"?>
&lt;strings xml:lang="en-US">
  &lt;str name="Figure">Fig&lt;/str>
  &lt;str name="Draft comment">ADDRESS THIS DRAFT COMMENT&lt;/str>
&lt;/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">&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
     to the translations in this plug-in. -->
&lt;langlist>
  &lt;lang xml:lang="vi"     filename="strings-vi.xml"/>
  &lt;lang xml:lang="vi-VN"  filename="strings-vi.xml"/>
&lt;/langlist></codeblock></p>
      <p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</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>&lt;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>