| 1 | <?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 2 | <!DOCTYPE html
|
|---|
| 3 | PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|---|
| 4 | <html xml:lang="en-us" lang="en-us">
|
|---|
| 5 | <head>
|
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
|---|
| 7 | <meta name="copyright" content="(C) Copyright 2005"/>
|
|---|
| 8 | <meta name="DC.rights.owner" content="(C) Copyright 2005"/>
|
|---|
| 9 | <meta name="DC.Type" content="reference"/>
|
|---|
| 10 | <meta name="DC.Title" content="Modifying or adding generated text"/>
|
|---|
| 11 | <meta name="abstract" content="Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <note> element."/>
|
|---|
| 12 | <meta name="description" content="Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <note> element."/>
|
|---|
| 13 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugins-overview.html"/>
|
|---|
| 14 | <meta name="DC.Relation" scheme="URI" content="../readme/DITA-globalization-xhtml.html"/>
|
|---|
| 15 | <meta name="DC.Format" content="XHTML"/>
|
|---|
| 16 | <meta name="DC.Identifier" content="plugin-addgeneratedtext"/>
|
|---|
| 17 | <meta name="DC.Language" content="en-us"/>
|
|---|
| 18 | <link rel="stylesheet" type="text/css" href="../commonltr.css"/>
|
|---|
| 19 | <link rel="stylesheet" type="text/css" href="../dita-ot-doc.css"/>
|
|---|
| 20 | <title>Modifying or adding generated text</title>
|
|---|
| 21 | </head>
|
|---|
| 22 | <body id="plugin-addgeneratedtext">
|
|---|
| 23 |
|
|---|
| 24 |
|
|---|
| 25 | <h1 class="title topictitle1">Modifying or adding generated text</h1>
|
|---|
| 26 |
|
|---|
| 27 |
|
|---|
| 28 | <div class="body refbody"><p class="shortdesc">Generated text is the term for strings that are automatically
|
|---|
| 29 | added by the build, such as "Note" before the contents of a <note>
|
|---|
| 30 | element.</p>
|
|---|
| 31 |
|
|---|
| 32 | <div class="section"><div class="p">The generated text extension point is used to add new
|
|---|
| 33 | strings to the default set of generated text. There are several reasons
|
|---|
| 34 | you may want to use this:<ul class="ul">
|
|---|
| 35 | <li class="li">It can be used to add new text for your own processing extensions;
|
|---|
| 36 | for example, it could be used to add localized versions of the string
|
|---|
| 37 | "User response" to aid in rendering troubleshooting information.</li>
|
|---|
| 38 |
|
|---|
| 39 | <li class="li">It can be used to override the default strings in the toolkit;
|
|---|
| 40 | for example, it could be used to reset the English string "Figure"
|
|---|
| 41 | to "Fig".</li>
|
|---|
| 42 |
|
|---|
| 43 | <li class="li">It can be used to add support for new languages (for non-PDF transforms
|
|---|
| 44 | only; PDF requires more complicated localization support). For example,
|
|---|
| 45 | it could be used to add support for Vietnamese or Gaelic; it could
|
|---|
| 46 | also be used to support a new variant of a previously supported language,
|
|---|
| 47 | such as Australian English.</li>
|
|---|
| 48 |
|
|---|
| 49 | </ul>
|
|---|
| 50 | </div>
|
|---|
| 51 | <dl class="dl">
|
|---|
| 52 | <dt class="dt dlterm"><samp class="ph codeph">dita.xsl.strings</samp></dt>
|
|---|
| 53 |
|
|---|
| 54 | <dd class="dd">Add new strings to generated text file. </dd>
|
|---|
| 55 |
|
|---|
| 56 | </dl>
|
|---|
| 57 | </div>
|
|---|
| 58 |
|
|---|
| 59 | <div class="example"><h2 class="title sectiontitle">Example: adding new strings</h2><p class="p">First copy the
|
|---|
| 60 | file <span class="ph filepath">xsl/common/strings.xml</span> to your plug-in,
|
|---|
| 61 | and edit it to contain the languages that you are providing translations
|
|---|
| 62 | for ("en-us" must be present). For this sample, copy the file into
|
|---|
| 63 | your plug-in as <span class="ph filepath">xsl/my-new-strings.xml</span>. The new
|
|---|
| 64 | strings file will look something like this:</p>
|
|---|
| 65 | <pre class="pre codeblock"><?xml version="1.0" encoding="utf-8"?>
|
|---|
| 66 | <!-- Provide strings for my plug-in; this plug-in supports
|
|---|
| 67 | English, Icelandic, and Russian. -->
|
|---|
| 68 | <langlist>
|
|---|
| 69 | <lang xml:lang="en" filename="mystring-en-us.xml"/>
|
|---|
| 70 | <lang xml:lang="en-us" filename="mystring-en-us.xml"/>
|
|---|
| 71 | <lang xml:lang="is" filename="mystring-is-is.xml"/>
|
|---|
| 72 | <lang xml:lang="is-is" filename="mystring-is-is.xml"/>
|
|---|
| 73 | <lang xml:lang="ru" filename="mystring-ru-ru.xml"/>
|
|---|
| 74 | <lang xml:lang="ru-ru" filename="mystring-ru-ru.xml"/>
|
|---|
| 75 | </langlist></pre>
|
|---|
| 76 | <p class="p">Next, copy the file <span class="ph filepath">xsl/common/strings-en-us.xml</span> to
|
|---|
| 77 | your plug-in, and replace the content with your own strings (be sure
|
|---|
| 78 | to give them unique name attributes). Do the same for each language
|
|---|
| 79 | that you are providing a translation for. For example, the file <span class="ph filepath">mystring-en-us.xml</span> might
|
|---|
| 80 | contain:</p>
|
|---|
| 81 | <pre class="pre codeblock"><?xml version="1.0" encoding="utf-8"?>
|
|---|
| 82 | <strings xml:lang="en-us">
|
|---|
| 83 | <str name="String1">English generated text</str>
|
|---|
| 84 | <str name="Another String">Another String in English</str>
|
|---|
| 85 | </strings></pre>
|
|---|
| 86 | <p class="p">Use the following extension code to include
|
|---|
| 87 | your strings in the set of generated text: </p>
|
|---|
| 88 | <pre class="pre codeblock"><plugin id="com.example.strings">
|
|---|
| 89 | <feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/>
|
|---|
| 90 | </plugin></pre>
|
|---|
| 91 | <p class="p">The string is now available to the "getString"
|
|---|
| 92 | template used in many DITA-OT XSLT files. For example, if processing
|
|---|
| 93 | in a context where the xml:lang value is "en-us", the following call
|
|---|
| 94 | would return "Another String in English":</p>
|
|---|
| 95 | <pre class="pre codeblock"><xsl:call-template name="getString">
|
|---|
| 96 | <xsl:with-param name="stringName" select="'Another String'"/>
|
|---|
| 97 | </xsl:call-template>
|
|---|
| 98 | </pre>
|
|---|
| 99 | <div class="note note"><span class="notetitle">Note:</span> If two plug-ins define the same string, the results
|
|---|
| 100 | will be non-deterministic, so multiple plug-ins should not try to
|
|---|
| 101 | create the same generated text string. One common way to avoid this
|
|---|
| 102 | problem is to ensure the name attributes used to look up the string
|
|---|
| 103 | value are related to the ID or purpose of your plug-in.</div>
|
|---|
| 104 | </div>
|
|---|
| 105 |
|
|---|
| 106 | <div class="example"><h2 class="title sectiontitle">Example: modifying existing strings</h2><p class="p">The
|
|---|
| 107 | process for modifying existing generated text is exactly the same
|
|---|
| 108 | as for adding new text, except that the strings you provide override
|
|---|
| 109 | values that already exist. To begin, set up the <span class="ph filepath">xsl/my-new-strings.xml</span> file
|
|---|
| 110 | in your plug-in as in the previous example. </p>
|
|---|
| 111 | <p class="p">Next, copy the
|
|---|
| 112 | file <span class="ph filepath">xsl/common/strings-en-us.xml</span> to your plug-in,
|
|---|
| 113 | and choose the strings you wish to change (be sure to leave the name
|
|---|
| 114 | attribute unchanged, because this is the key used to look up the string).
|
|---|
| 115 | Create a strings file for each language that needs to modify existing
|
|---|
| 116 | strings. For example, the new file <span class="ph filepath">mystring-en-us.xml</span> might
|
|---|
| 117 | contain:</p>
|
|---|
| 118 | <pre class="pre codeblock"><?xml version="1.0" encoding="utf-8"?>
|
|---|
| 119 | <strings xml:lang="en-us">
|
|---|
| 120 | <str name="Figure">Fig</str>
|
|---|
| 121 | <str name="Draft comment">ADDRESS THIS DRAFT COMMENT</str>
|
|---|
| 122 | </strings></pre>
|
|---|
| 123 | <p class="p">To integrate the new strings, use the
|
|---|
| 124 | same method as above to add these strings to your <span class="ph filepath">plugin.xml</span> file.
|
|---|
| 125 | Once this plug-in is integrated, where XHTML output previously generated
|
|---|
| 126 | the term "Figure", it will now generate "Fig"; where it previously
|
|---|
| 127 | generated "Draft comment", it will now generate "ADDRESS THIS DRAFT
|
|---|
| 128 | COMMENT". The same strings in other languages will not be modified
|
|---|
| 129 | unless you also provide new versions for those languages.</p>
|
|---|
| 130 | <div class="note note"><span class="notetitle">Note:</span> If
|
|---|
| 131 | two plug-ins override the same string in the same language, the results
|
|---|
| 132 | will be non-deterministic (either string may be used under different
|
|---|
| 133 | conditions). Multiple plug-ins should not override the same generated
|
|---|
| 134 | text string for a single language.</div>
|
|---|
| 135 | </div>
|
|---|
| 136 |
|
|---|
| 137 | <div class="example"><h2 class="title sectiontitle">Example: adding a new language</h2><div class="p">The process
|
|---|
| 138 | for adding a new language is exactly the same as for adding new text,
|
|---|
| 139 | except you are effectively just translating an existing strings file.
|
|---|
| 140 | To begin, set up the <span class="ph filepath">xsl/my-new-strings.xml</span> file
|
|---|
| 141 | in your plug-in as in the previous examples. In this case, the only
|
|---|
| 142 | difference is that you are adding a mapping to new languages; for
|
|---|
| 143 | example, the following file would be used to set up support for Vietnamese:<pre class="pre codeblock"><?xml version="1.0" encoding="utf-8"?>
|
|---|
| 144 | <!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
|
|---|
| 145 | to the translations in this plug-in. -->
|
|---|
| 146 | <langlist>
|
|---|
| 147 | <lang xml:lang="vi" filename="strings-vi.xml"/>
|
|---|
| 148 | <lang xml:lang="vi-vn" filename="strings-vi.xml"/>
|
|---|
| 149 | </langlist></pre>
|
|---|
| 150 | </div>
|
|---|
| 151 | <p class="p">Next, copy the file <span class="ph filepath">xsl/common/strings-en-us.xml</span> to
|
|---|
| 152 | your plug-in, and rename it to match the language you wish to add.
|
|---|
| 153 | For example, to support Vietnamese strings you may want to pick a
|
|---|
| 154 | name like <span class="ph filepath">strings-vi.xml</span>. In that file, change
|
|---|
| 155 | the <samp class="ph codeph">xml:lang</samp> attribute on the root element to match
|
|---|
| 156 | your new language.</p>
|
|---|
| 157 | <p class="p">Once the file is ready, translate the contents
|
|---|
| 158 | of each <samp class="ph codeph"><str></samp> element (be sure to leave the name
|
|---|
| 159 | attribute unchanged). Repeat this process for each new language you
|
|---|
| 160 | wish to add.</p>
|
|---|
| 161 | <p class="p">To integrate the new languages, use the same method
|
|---|
| 162 | as above to add these strings to your <span class="ph filepath">plugin.xml</span> file.
|
|---|
| 163 | Once this plug-in is integrated, non-PDF builds will include support
|
|---|
| 164 | for Vietnamese; instead of generating the English word "Caution",
|
|---|
| 165 | the element <samp class="ph codeph"><note type="caution" xml:lang="vi"></samp> may
|
|---|
| 166 | generate something like "<dfn class="term" xml:lang="vi" lang="vi">chú ý</dfn>".</p>
|
|---|
| 167 | <div class="note note"><span class="notetitle">Note:</span> If
|
|---|
| 168 | two plug-ins add support for the same language using different
|
|---|
| 169 | values, the results will be non-deterministic (translations from either
|
|---|
| 170 | plug-in may be picked up under different conditions).</div>
|
|---|
| 171 | </div>
|
|---|
| 172 |
|
|---|
| 173 | </div>
|
|---|
| 174 |
|
|---|
| 175 | <div class="related-links">
|
|---|
| 176 | <div class="familylinks">
|
|---|
| 177 | <div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../dev_ref/plugins-overview.html" title="The DITA Open Toolkit comes with a built in mechanism for adding in extensions through plug-ins. These plug-ins may do a wide variety of things, such as adding support for specialized DITA DTDs or Schemas, integrating processing overrides, or even providing entirely new output transforms. Plug-ins are the best way to extend the toolkit in a way that is consistent, easily sharable, and easy to preserve through toolkit upgrades.">Creating DITA-OT plug-ins</a></div>
|
|---|
| 178 | </div>
|
|---|
| 179 | <div class="relinfo relref"><strong>Related reference</strong><br/>
|
|---|
| 180 | <div><a class="link" href="../readme/DITA-globalization-xhtml.html" title="The DITA Open Toolkit (DITA-OT) supports over 50 languages and language variants for the HTML- and XHTML-based transformations, for example, Eclipse Help, HTML Help, and TocJS.">Languages supported by the core toolkit</a></div>
|
|---|
| 181 | </div>
|
|---|
| 182 | </div>
|
|---|
| 183 |
|
|---|
| 184 | </body>
|
|---|
| 185 | </html>
|
|---|
