discontinued / server · Files

index.html 290 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><title>Best Practices for XML Internationalization</title><style type="text/css">

</style><link rel="stylesheet" href="local.css" type="text/css"/><link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-WG-NOTE.css"/></head><body><div style="text-align:center;"><p>[ <a href="#contents">contents</a> ]</p></div><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"/></a></p>
<h1><a name="title" id="title"></a>Best Practices for XML Internationalization</h1>
<h2><a name="w3c-doctype" id="w3c-doctype"></a>W3C Working Group Note 13 February 2008</h2><dl><dt>This version:</dt><dd> 
 		<a href="http://www.w3.org/TR/2008/NOTE-xml-i18n-bp-20080213/">http://www.w3.org/TR/2008/NOTE-xml-i18n-bp-20080213/</a>
	 </dd><dt>Latest version:</dt><dd> 
		 <a href="http://www.w3.org/TR/xml-i18n-bp/">http://www.w3.org/TR/xml-i18n-bp/</a>
		</dd><dt>Previous version:</dt><dd><a href="http://www.w3.org/TR/2007/WD-xml-i18n-bp-20071031/">http://www.w3.org/TR/2007/WD-xml-i18n-bp-20071031/</a></dd><dt>Editors:</dt><dd>Yves Savourel, ENLASO Corporation</dd><dd>Jirka Kosek, Invited Expert</dd><dd>Richard Ishida, W3C</dd></dl><p>This document is also available in these non-normative formats: <a href="xml-i18n-bp.pdf">PDF version</a> and <a href="xml-i18n-bp-diff.html">XHTML Diff markup to publication from 31 October 2007</a>.</p><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2008 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr/><div>
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>This document provides a set of guidelines for developing XML documents and schemas that are internationalized properly. Following the best practices describes here allow both the developer of XML applications, as well as the author of XML content to create material in different languages.</p></div><div>
<h2><a name="status" id="status"></a>Status of this Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at <a href="http://www.w3.org/TR/">http://www.w3.org/TR/</a>.</em></p><p>This is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#WGNote">W3C Working Group Note</a> of  "<span class="quote">Best Practices for XML Internationalization</span>". This document was developed by the <a href="http://www.w3.org/International/its/">Internationalization Tag Set (ITS) Working Group</a>,
part of the <a href="http://www.w3.org/International/Activity">W3C Internationalization Activity</a>.</p><p>Feedback about this document is encouraged. Send your comments to <a href="mailto:www-i18n-comments@w3.org?subject=[Comment on xml-i18n-bp WD]">www-i18n-comments@w3.org</a>. Use "[Comment on xml-i18n-bp WD]" in the subject line of your email, followed by a brief subject. The <a href="http://lists.w3.org/Archives/Public/www-i18n-comments/">archives</a> for this list are publicly available.</p><p>Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p> This document was produced by a group operating under the
      <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
      February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/37139/status">public
      list of any patent disclosures</a> made in connection with the
      deliverables of the group; that page also includes instructions
      for disclosing a patent. An individual who has actual knowledge
      of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
      Claim(s)</a> must disclose the information in accordance with
      <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
      6 of the W3C Patent Policy</a>. </p></div><div class="toc">
<h2><a name="contents" id="contents"></a>Table of Contents</h2><div class="toc"><div class="toc1">1 <a href="#idIntro">Introduction</a><div class="toc2">1.1 <a href="#idIntroWho">Who should use this document</a></div>
<div class="toc2">1.2 <a href="#idIntroHow">How to use this document</a><div class="toc3">1.2.1 <a href="#HowToDev">Designers and developers of XML applications</a></div>
<div class="toc3">1.2.2 <a href="#HowToAuth">Users and authors of XML content</a></div>
</div>
</div>
<div class="toc1">2 <a href="#DesignTime">When Designing an XML Application</a><ul style="margin-top:0;margin-bottom:0;"><li class="toc-technique"><a href="#DevLang">Best Practice 1: Defining markup for natural language labelling</a></li><li class="toc-technique"><a href="#DevDir">Best Practice 2: Defining markup to specify text direction</a></li><li class="toc-technique"><a href="#DevAttributes">Best Practice 3: Avoiding translatable attribute values</a></li><li class="toc-technique"><a href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a></li><li class="toc-technique"><a href="#DevTransOver">Best Practice 5: Defining markup to override translate information</a></li><li class="toc-technique"><a href="#DevSeg">Best Practice 6: Providing 
		information related to text segmentation</a></li><li class="toc-technique"><a href="#DevRuby">Best Practice 7: Defining markup for  ruby text</a></li><li class="toc-technique"><a href="#DevLocNote">Best Practice 8: Defining markup for  notes to localizers</a></li><li class="toc-technique"><a href="#DevUniqueID">Best Practice 9: Defining markup for  unique identifiers</a></li><li class="toc-technique"><a href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a></li><li class="toc-technique"><a href="#DevTermOver">Best Practice 11: Defining markup for specifying or overriding terminology-related information</a></li><li class="toc-technique"><a href="#DevMLDoc">Best Practice 12: Working with multilingual documents</a></li><li class="toc-technique"><a href="#DevElemNames">Best Practice 13: Naming elements and attributes</a></li><li class="toc-technique"><a href="#DevSpan">Best Practice 14: Defining a span-like element</a></li><li class="toc-technique"><a href="#DevITSRules">Best Practice 15: Documenting internationalization and localization features of your schema</a></li></ul></div>
<div class="toc1">3 <a href="#AuthoringTime">When Authoring XML Content</a><ul style="margin-top:0;margin-bottom:0;"><li class="toc-technique"><a href="#AuthLang">Best Practice 16: Specifying the language of content</a></li><li class="toc-technique"><a href="#AuthDir">Best Practice 17: Specifying text directionality</a></li><li class="toc-technique"><a href="#AuthTransOver">Best Practice 18: Overriding information about what should be translated</a></li><li class="toc-technique"><a href="#AuthUniqueID">Best Practice 19: Assigning unique identifiers</a></li><li class="toc-technique"><a href="#AuthCDATA">Best Practice 20: Avoiding CDATA sections</a></li><li class="toc-technique"><a href="#AuthLocNote">Best Practice 21: Providing notes for localizers</a></li><li class="toc-technique"><a href="#AuthInsText">Best Practice 22: Working with inserted text</a></li><li class="toc-technique"><a href="#AuthTermOver">Best Practice 23: Identifying terms</a></li><li class="toc-technique"><a href="#AuthMarkupAsText">Best Practice 24: Storing markup from another format</a></li></ul></div>
<div class="toc1">4 <a href="#Generic">Generic Techniques</a><div class="toc2">4.1 <a href="#GenericWritingITSRules">Writing ITS Rules</a><div class="toc3">4.1.1 <a href="#GenPrecInherit">Precedence and Inheritance</a></div>
<div class="toc3">4.1.2 <a href="#GenNamespaces">Dealing with namespaces</a></div>
<div class="toc3">4.1.3 <a href="#GenXPath">Create your XPath expressions with care</a></div>
</div>
<div class="toc2">4.2 <a href="#generic_insertatt">Example of adding an attribute to an existing schema</a><div class="toc3">4.2.1 <a href="#generic-includeinxsd">Including xml:lang in XML Schema</a></div>
<div class="toc3">4.2.2 <a href="#generic-includeinrng">Including xml:lang in RELAX NG</a></div>
<div class="toc3">4.2.3 <a href="#generic-includeindtd">Including xml:lang in an XML DTD</a></div>
</div>
</div>
<div class="toc1">5 <a href="#Modularization">ITS Applied to Existing Formats</a><div class="toc2">5.1 <a href="#its-plus-xhtml10">ITS and XHTML 1.0</a><div class="toc3">5.1.1 <a href="#integration-its-xhtml">Integrating  ITS into XHTML</a></div>
<div class="toc3">5.1.2 <a href="#integration-its-xhtmlmod">Using XHTML Modularization 1.1 for the Definition of ITS</a></div>
<div class="toc3">5.1.3 <a href="#integration-its-xhtml-nvdl">Using NVDL to integrate ITS into XHTML</a></div>
<div class="toc3">5.1.4 <a href="#relating-its-plus-xhtml">Associating existing XHTML markup with ITS</a></div>
</div>
<div class="toc2">5.2 <a href="#tei-modularization">ITS and TEI</a><div class="toc3">5.2.1 <a href="#tei-plus-its">Integrating ITS into TEI</a></div>
</div>
<div class="toc2">5.3 <a href="#xmlspec">ITS and XML Spec</a><div class="toc3">5.3.1 <a href="#its-xmlspec">Integration of ITS into XML Spec</a></div>
<div class="toc3">5.3.2 <a href="#relating-xmlspec-plus-its">Associating existing XML Spec markup with ITS</a></div>
</div>
<div class="toc2">5.4 <a href="#dita">ITS and DITA</a><div class="toc3">5.4.1 <a href="#its-dita">Integration of ITS into DITA</a></div>
<div class="toc3">5.4.2 <a href="#dita-its-relating">Associating existing DITA markup with ITS</a></div>
</div>
<div class="toc2">5.5 <a href="#glade">ITS and GladeXML</a><div class="toc3">5.5.1 <a href="#its-glade">Integration of ITS into GladeXML</a></div>
<div class="toc3">5.5.2 <a href="#glade-its-relating">Associating Existing GladeXML Markup with ITS</a></div>
</div>
<div class="toc2">5.6 <a href="#docbook">ITS and DocBook</a><div class="toc3">5.6.1 <a href="#docbook-plus-its">Integration of ITS into DocBook</a></div>
<div class="toc3">5.6.2 <a href="#relating-docbook-plus-its">Associating existing DocBook markup with ITS</a></div>
</div>
</div>
</div>
<h3><a name="appendices" id="appendices"></a>Appendices</h3><div class="toc1">A <a href="#d4e5690">References</a> (Non-Normative)</div>
<div class="toc1">B <a href="#Acknowledgements">Acknowledgements</a> (Non-Normative)</div>
</div><hr/><div class="body"><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="idIntro" id="idIntro"></a>1 Introduction</h2><p>This document is a complement to the W3C Recommendation <cite>Internationalization Tag Set (ITS) Version 1.0</cite> <a title="Internationalization Tag Set (ITS) Version 1.0" href="#itsspec">[ITS]</a>. However, not all internationalization-related issues can be resolved by the special markup described in ITS. The best practices in this document therefore go beyond application of ITS markup to address  a number of problems that can be avoided by correctly designing the XML format, and by applying a few additional guidelines when developing content. </p><p>This document and <cite>Internationalization Tag Set (ITS) Version 1.0</cite> <a title="Internationalization Tag Set (ITS) Version 1.0" href="#itsspec">[ITS]</a> implement requirements formulated in <cite>Internationalization and Localization Markup Requirements</cite> <a title="Internationalization and Localization Markup Requirements" href="#itsreq">[ITS REQ]</a>.</p><p>This set of best practices does not cover all topics about internationalization for XML. Other useful reference material includes: <em>Character Model for the World Wide Web 1.0: Fundamentals</em> <a title="Character Model for the World Wide Web 1.0: Fundamentals" href="#charmod">[CharMod]</a>, and <em>Unicode in XML and other Markup Languages</em> <a title="Unicode in XML and other Markup Languages" href="#utr20">[Unicode in XML]</a>.</p><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="idIntroWho" id="idIntroWho"></a>1.1 Who should use this document</h3><p>This document is divided into two main sections:</p><ul><li><p>The first one is intended for the <em>designers and developers of XML applications (also referred to here as '<span class="qterm">schemas</span>' or '<span class="qterm">formats</span>')</em>.</p></li><li><p>The second is intended for the <em>XML content authors</em>. This includes users modifying the original content,  such as translators.</p></li></ul></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="idIntroHow" id="idIntroHow"></a>1.2 How to use this document</h3><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="HowToDev" id="HowToDev"></a>1.2.1 Designers and developers of XML applications</h4><p><a class="section-ref" href="#DesignTime">Section 2: When Designing an XML Application</a> provides a list of some of the important design choices you should make in order to ensure the internationalization of your format.</p><p><a class="section-ref" href="#Generic">Section 4: Generic Techniques</a> provides additional generic techniques such as writing ITS rules or adding an attribute to a schema. Such techniques apply to many of the best practices.</p><p><a class="section-ref" href="#Modularization">Section 5: ITS Applied to Existing Formats</a> provides a set of concrete examples on how to apply ITS to existing XML based formats. This section illustrates many of the guidelines in this document.</p></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="HowToAuth" id="HowToAuth"></a>1.2.2 Users and authors of XML content</h4><p><a class="section-ref" href="#AuthoringTime">Section 3: When Authoring XML Content</a> provides a number of guidelines on how to create content with internationalization in mind. Many of these best practices are relevant regardless of whether or not your  XML format was  developed especially for internationalization.</p><p><a class="section-ref" href="#GenericWritingITSRules">Section 4.1: Writing ITS Rules</a> provides practical guidelines on how to write ITS rules. Such techniques may be useful when applying some of the more advanced authoring best practices.</p></div></div></div><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="DesignTime" id="DesignTime"></a>2 When Designing an XML Application</h2><p>Designers and developers of XML applications should take into account the following best practices:</p><a name="DevSummaryTable" id="DevSummaryTable"></a><table border="1" cellpadding="5" cellspacing="1"><thead><tr><th>Best Practice</th><th>Implementing as a new feature</th><th>Handling legacy markup</th></tr></thead><tbody align="left" valign="top"><tr><td><a class="technique-ref" href="#DevLang">Defining markup for natural language labelling</a></td><td>Make sure the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute is defined for the root element of your document, and for any element where a change of language may occur.</td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule">its:langRule</a></code> element to specify what attribute or element is used instead of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>.</td></tr><tr><td><a class="technique-ref" href="#DevDir">Defining markup to specify text direction</a></td><td>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> attribute is defined for the root element of your document, and for any element that has text content.</td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#dirRule">its:dirRule</a></code> element to associate the different directionality indicators with their equivalents in ITS.</td></tr><tr><td><a class="technique-ref" href="#DevAttributes">Avoiding translatable attribute values</a></td><td>Make sure you store all translatable text as element content, not as attribute values.</td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to specify what attributes are translatable.</td></tr><tr><td><a class="technique-ref" href="#DevTrans">Indicating which elements and attributes should be translated</a></td><td colspan="2"><a href="#DevITSRules">Provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> elements to indicate which elements have non-translatable content.</td></tr><tr><td><a class="technique-ref" href="#DevTransOver">Defining markup to override translate information</a></td><td>
     <ul><li><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute is defined for the root element of your documents, and for any element that has text content.</p></li><li><p>It is also recommended that you  define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one, and within that the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element. Content authors can then use these elements to globally change the default translate rules for specific elements and attributes.</p></li></ul>
    </td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to associate this mechanism with the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>.</td></tr><tr><td><a class="technique-ref" href="#DevSeg">Providing 
		information related to text segmentation</a></td><td colspan="2"><a href="#DevITSRules">Provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#withinTextRule">its:withinTextRule</a></code> elements to indicate which elements should be treated as either part of their parents, or as a nested but independent run of text. By default, element boundaries are assumed to correspond to segmentation boundaries.</td></tr><tr><td><a class="technique-ref" href="#DevRuby">Defining markup for  ruby text</a></td><td>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> element and its children are defined for all elements where there is text content.</td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule">its:rubyRule</a></code> element to associate your ruby markup with its equivalent in ITS.</td></tr><tr><td><a class="technique-ref" href="#DevLocNote">Defining markup for  notes to localizers</a></td><td>
     <ul><li><p>Make sure the attributes <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> are defined in your schema. This markup allows content authors to provide localization-related notes as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute values, or to point to the location of the relevant note text using <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code>.</p></li><li><p>It is also recommended that you define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one, and within that the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element and its related markup. Content authors  can use this markup to specify localization-related notes. Within the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element, notes can be stored in the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote">its:locNote</a></code> element.</p></li></ul>
    </td><td><a href="#DevITSRules">Provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element to associate your notes markup with its equivalent in ITS.</td></tr><tr><td><a class="technique-ref" href="#DevUniqueID">Defining markup for  unique identifiers</a></td><td colspan="2">Make sure that elements with translatable content can be associated with a unique identifier.</td></tr><tr><td><a class="technique-ref" href="#DevTerm">Identifying terminology-related elements</a></td><td colspan="2"><a href="#DevITSRules">Provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> elements to indicate which elements are terms and information related to them (e.g. definitions).</td></tr><tr><td><a class="technique-ref" href="#DevTermOver">Defining markup for specifying or overriding terminology-related information</a></td><td colspan="2">
     <ul><li><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> attributes are defined for any element that has text content.</p></li><li><p>It is also recommended to define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one. The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element provides access to the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> element which can be used to override terminology-related information globally.</p></li></ul>
    </td></tr><tr><td><a class="technique-ref" href="#DevMLDoc">Working with multilingual documents</a></td><td colspan="2">For documents that need to go through some localization tasks, always store the localized version of the text in a separate document.</td></tr><tr><td><a class="technique-ref" href="#DevElemNames">Naming elements and attributes</a></td><td>
     <ul><li><p>Make sure the names of the elements and attributes of your schema reflect their functions, rather than one possible way of rendering their content.</p></li><li><p>Also, if possible, avoid element names which do not follow a fixed naming scheme (for example, element names that serve also as identifiers).</p></li></ul>
	</td><td>Not applicable</td></tr><tr><td><a class="technique-ref" href="#DevSpan">Defining a span-like element</a></td><td>Make sure you define a <code>span</code>-like element in your schema that will allow authors to associate arbitrary content with  properties such as directionality, language information, etc.</td><td>If no <code>span</code>-like element already exists in your schema, you may be able to use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code>.</td></tr><tr><td><a class="technique-ref" href="#DevITSRules">Documenting internationalization and localization features of your schema</a></td><td colspan="2">Make sure you document the internationalization and localization aspects of your schema by providing a set of relevant ITS rules in a single standalone ITS Rules document.</td></tr></tbody></table><p>Where it says "How to implement this as a new feature", this section describes how to create new schemas or add new features to existing schemas. When doing this you may need to take into account the following:</p><ul><li><p>Think twice before creating your own schema. Seriously consider using existing formats such as <a href="#dita10">DITA</a>, DocBook, Open Document Format, Office Open XML, XML User Interface Language, Universal Business Language, etc. Those formats have many useful insights already built in.</p></li><li><p>Check carefully whether an existing format comes with a built-in capability for modification. DocBook and DITA, for example, come with their own set of features for adapting their format to special needs.</p></li><li><p>The modification mechanisms available will depend on the schema language (DTD, XML Schema, RELAX NG, etc.) For example, namespace-based modularization of schemas is difficult to achieve with DTDs.</p><p><a href="#nvdl">NVDL</a> is an example of a meta-schema language was designed especially
  to allow  integration of several existing vocabularies into a single XML
  vocabulary without the need to know the details of source schemas. This means
  that with NVDL you can usually create a schema for compound documents
  more easily than with other schema technologies.</p></li><li><p>Each schema language provides different ways of extending or modifying existing schemas. Some examples are the <a href="http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/#ref23">include</a>, <a href="http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/#ref31">import</a> or <a href="http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/#ref52">redefine</a> mechanisms in XML Schema.</p></li><li><p>Some processors do not implement support for all schema language constructs, due to erroneous implementations or differences in conformance profiles (e.g. see the conformance requirements to <a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/#concepts-conformance">XML Schema 
part 1</a>). Therefore a schema which works in one environment may not work in a different one.</p></li><li><p>What is possible also depends on the features of the schema which the modification is targeting. For example:</p><ul><li><p>An XML Schema <code>redefine</code> is only possible if the modified schema has been created with named types.</p></li><li><p>If you are working with XML Schema, you can only apply the technique of '<span class="qterm">chameleon</span>' or '<span class="qterm">proxy</span>' schemas (see <a href="http://www.xfront.com/ZeroOneOrManyNamespaces.html">http://www.xfront.com/ZeroOneOrManyNamespaces.html</a>) if the '<span class="qterm">chameleon</span>' schemas have no namespace. For example, the XML Schema document for ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/its.xsd">XML Schema document for ITS</a> has a target namespace and therefore cannot be a '<span class="qterm">chameleon</span>' schema.</p></li></ul></li></ul><div class="note"><p><span class="note-head">Note: </span>The considerations above are only a portion of what you need to take into account. You need to know a lot more when diving into schema modularization.</p></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevLang" name="DevLang" href="#DevLang">Best Practice 1: Defining markup for natural language labelling</a></div><div class="rule">Provide a way for authors to specify the natural language of content using ITS markup, or document equivalent legacy markup in an ITS
			Rules document.</div><div class="description"><p>The XML namespace provides the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute and the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#language-information">ITS Language Information data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule">its:langRule</a></code> element to address this requirement.</p><p><strong>How to implement this as a new feature</strong></p><p>Make sure the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute is defined for the root element of your document, and for any element where a change of language may occur.</p><p>For examples of how to add attributes in your existing schema see <a class="section-ref" href="#generic_insertatt">Section 4.2: Example of adding an attribute to an existing schema</a>.</p><p>Some XML documents may be designed to store data without natural language content. In these cases, there is no need for the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute.</p><p>The scope of the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute applies to both the attributes and the content of the element where it appears, therefore one cannot specify different languages for an attribute and the element content. ITS does not provide a remedy for this. Instead, it is recommended that you <a href="#DevAttributes">avoid translatable attributes</a>.</p><p>Make sure that the definition of the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute allows for empty values. That is:
    </p><ul><li><p>In a DTD you must not use <code>NMTOKEN</code> as the data type, instead use <code>CDATA</code>.</p></li><li><p>In XML Schema the built-in data type <code>language</code> does not allow empty values. However, the declaration for <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in the XML Schema document for the XML namespace at <a href="http://www.w3.org/2001/xml.xsd">http://www.w3.org/2001/xml.xsd</a> does allow for empty values and therefore can be used.</p></li></ul><p>
   </p><p>It is <em>not recommended</em> to use your own attribute or element to specify the language of the content. The <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute is supported by various XML technologies such as XPath and XSLT (e.g. the <code>lang()</code> function). Using something different would diminish the interoperability of your documents and reduce your ability to take advantage of some XML applications.</p><div class="note"><p><span class="note-head">Note: </span>If you need to specify language as data or meta-data about something external to the document, do it with an attribute different from <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>. For more information see the article <a href="http://www.w3.org/International/questions/qa-when-xmllang">xml:lang in XML document schemas</a>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e652" id="d4e652"></a>Example 1: Language information not applicable to the content of the element where it is used</div><p>In XHTML the language of a file linked with the <code>a</code> element is indicated with a <code>hreflang</code> attribute because it does not apply to the content of the <code>a</code> element.</p><div class="exampleInner"><pre>&lt;a xml:lang="en" href="german.html" hreflang="de"&gt;Click here for German&lt;/a&gt;</pre></div></div><p>If you have different languages in the attribute values and content of an element, consider nesting elements, if possible. See <a href="http://www.w3.org/TR/i18n-html-tech-lang/#ri20050128.175100333">Handling attribute values and element content in different languages</a>.</p></div><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with an existing schema where there is a way to specify content language that uses something other than  the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute (but still uses the same values as <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>), you should  <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule">its:langRule</a></code> element to specify what attribute or element is used instead of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devlang-1" id="EX-devlang-1"></a>Example 2: Dealing with a non-standard way of declaring language information</div><p>In this document the <code>langcode</code> element is used to specify the language of the <code>text</code> element. The <code>langcode</code> element has no inheritance behavior equivalent to the one of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>.</p><div class="note"><p><span class="note-head">Note: </span>This example is a multilingual document, which has its own set of issues (see  <a class="technique-ref" href="#DevMLDoc">Best Practice 12: Working with multilingual documents</a>).</p></div><pre>&lt;myRes&gt;
 &lt;messages&gt;
  &lt;msg id="1"&gt;
   &lt;langcode&gt;en&lt;/langcode&gt;
   &lt;text&gt;Cannot find file.&lt;/text&gt;
  &lt;/msg&gt;
  &lt;msg id="2"&gt;
   &lt;langcode&gt;fr&lt;/langcode&gt;
   &lt;text&gt;Fichier non trouvé.&lt;/text&gt;
  &lt;/msg&gt;
 &lt;/messages&gt;
&lt;/myRes&gt;</pre><p>[<a href="EX-devlang-1.xml">Example's source code</a>]</p><p>The corresponding ITS Rules document contains an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule">its:langRule</a></code> element that specifies that the <code>langcode</code> element holds the same values as the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute and applies to the <code>text</code> element.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:langRule selector="//text[../langcode]" langPointer="../langcode"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devlang-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>Information about the language of content can be very important for correctly rendering or styling text in some scripts, applying spell-checkers during content authoring, appropriate selection of voice for text-to-speech systems, script-based processing, and numerous other reasons. You must provide a standard way to specify the language for the document as a whole, but also for parts of the document where the language changes.
   
  </p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e754" name="BId4e754">Background information</a></h4><ul><li>Internationalization FAQ: xml:lang in XML document schemas.<br/> <a href="http://www.w3.org/International/questions/qa-when-xmllang">http://www.w3.org/International/questions/qa-when-xmllang</a></li><li>Mechanisms for declaring language in HTML<br/> <a href="http://www.w3.org/TR/i18n-html-tech-lang/#ri20050208.095812479">http://www.w3.org/TR/i18n-html-tech-lang/#ri20050208.095812479</a></li></ul><h4><a id="RLd4e754" name="RLd4e754">Reference links</a></h4><ul><li>Description of the language identification mechanism in the XML specification.<br/> <a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">http://www.w3.org/TR/REC-xml/#sec-lang-tag</a></li><li>The "Language Information" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#language-information">http://www.w3.org/TR/2007/REC-its-20070403/#language-information</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e754" name="Rd4e754">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevDir" name="DevDir" href="#DevDir">Best Practice 2: Defining markup to specify text direction</a></div><div class="rule">Provide a way for authors to specify the direction of text using ITS markup, or document equivalent legacy markup in an ITS Rules
			document.</div><div class="description"><p>In scripts such as Arabic and Hebrew characters may run from both left to right and right to left when displayed. Directional markup allows you to manage the flow of characters. For an example of how directional markup is used see <a href="http://www.w3.org/International/tutorials/bidi-xhtml/">Creating (X)HTML Pages in Arabic &amp; Hebrew</a>.</p><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#directionality">ITS Directionality data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> attribute and the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#dirRule">its:dirRule</a></code> element to address this requirement.</p><p><strong>How to implement this as a new feature</strong></p><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> attribute is defined for the root element of your document, and for any element that has text content.</p><p>For examples of how to add attributes in your existing schema see <a class="section-ref" href="#generic_insertatt">Section 4.2: Example of adding an attribute to an existing schema</a>.</p><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with an existing schema where there is a way to specify text directionality that is not implemented using the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> attribute, you should <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#dirRule">its:dirRule</a></code> element to associate the different directionality indicators with their equivalents in ITS.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devdir-1" id="EX-devdir-1"></a>Example 3: Specifying text directionality where  non-ITS markup has been used.</div><p>In this document the <code>textdir</code> attribute is used to specify directionality of a text run.</p><pre>
<span class="element">&lt;text <span class="attribute">xml:lang</span>="en"&gt;</span>
 <span class="element">&lt;body&gt;</span>
  <span class="element">&lt;par&gt;</span>In Hebrew, the title
     <span class="element">&lt;quote <span class="attribute">xml:lang</span>="he" <span class="attribute">textdir</span>="r2l"&gt;</span><span dir="rtl">פעילות הבינאום, W3C</span><span class="element">&lt;/quote</span>&gt;
     means <span class="element">&lt;quote&gt;</span>Internationalization Activity, W3C<span class="element">&lt;/quote</span>&gt;.<span class="element">&lt;/par</span>&gt;
 <span class="element">&lt;/body</span>&gt;
<span class="element">&lt;/text</span>&gt;</pre><div class="note"><p><span class="note-head">Note: </span>This example shows the directionality of the source text correctly. This is to ensure that you understand the concepts being described. For such display, you need a sophisticated editor that resolves directionality of the source text correctly. Many editors are not yet this sophisticated. See the related discussion about <a href="http://www.w3.org/TR/i18n-html-tech-bidi/#d2e283">Problems with bidirectional source text</a> in <a title="Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content" href="#bidixhtmlbp">[Bidi in X/HTML]</a>.</p></div><p>[<a href="EX-devdir-1.xml">Example's source code</a>]</p><p>The corresponding ITS Rules document contains a set of <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#dirRule">its:dirRule</a></code> elements that specifies the relationships between the <code>textdir</code> attribute and the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#directionality">ITS Directionality data category</a>.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:dirRule selector="//*[@textdir='l2r']" dir="ltr"/&gt;
 &lt;its:dirRule selector="//*[@textdir='r2l']" dir="rtl"/&gt;
 &lt;its:dirRule selector="//*[@textdir='lro']" dir="lro"/&gt;
 &lt;its:dirRule selector="//*[@textdir='rlo']" dir="rlo"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devdir-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>Generally the Unicode bidirectional algorithm will produce the correct ordering of mixed directionality text in scripts such as Arabic and Hebrew. Sometimes, however, additional help is needed. For instance, in the sentence of <a class="example-ref" href="#DevDir-bidineeded">Example 4</a> the 'W3C' and the comma should appear to the left side of the quotation. This cannot be achieved using the bidirectional algorithm alone.</p><div class="exampleOuter"><div class="exampleHeader"><a name="DevDir-bidineeded" id="DevDir-bidineeded"></a>Example 4: Sentence where bidirectional markup is needed for a proper display</div><p>The following will display incorrectly, since no directional markup has been used:</p><p>The title says "<span xml:lang="he" lang="he">פעילות הבינאום, W3C</span>" in Hebrew.</p><p>The text 'W3C' and the comma should be to the left of the quoted Hebrew text. If your browser supports bidirectional display, the following should appear correctly, since directional markup has been added to the element surrounding the quote:</p><p>The title says "<span xml:lang="he" lang="he" dir="rtl">פעילות הבינאום, W3C</span>" in Hebrew.</p></div><p>The desired effect can be achieved using Unicode control characters, but this is not recommended (See <cite>Unicode in XML and other Markup Languages</cite> <a title="Unicode in XML and other Markup Languages" href="#utr20">[Unicode in XML]</a>). Markup is needed to establish the default directionality of a document, and to change that where appropriate by creating nested embedding levels.</p><p>Markup is also occasionally needed  to disable the effects of the bidirectional algorithm for a specified range of text.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e907" name="BId4e907">Background information</a></h4><ul><li>Internationalization FAQ: What you need to know about the bidi algorithm and inline markup<br/> <a href="http://www.w3.org/International/articles/inline-bidi-markup/">http://www.w3.org/International/articles/inline-bidi-markup/</a></li><li>Authoring Techniques for XHTML &amp; HTML Internationalization: Handling Bidirectional Text 1.0<br/> <a href="http://www.w3.org/TR/i18n-html-tech-bidi/#ri20030728.094313871">http://www.w3.org/TR/i18n-html-tech-bidi/#ri20030728.094313871</a></li><li>Unicode Technical Report #20: Unicode in XML and other Markup Languages<br/> <a href="http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/">http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/</a></li></ul><h4><a id="RLd4e907" name="RLd4e907">Reference links</a></h4><ul><li>The "Directionality" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#directionality">http://www.w3.org/TR/2007/REC-its-20070403/#directionality</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e907" name="Rd4e907">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevAttributes" name="DevAttributes" href="#DevAttributes">Best Practice 3: Avoiding translatable attribute values</a></div><div class="rule">Do not define attribute values that will contain user readable content. Use elements
			for such content.</div><div class="description"><p><strong>How to implement this as a new feature</strong></p><p>Make sure you store all translatable text as element content, not as attribute values.</p><div class="exampleOuter"><div class="exampleHeader"><a name="dev-attr-1" id="dev-attr-1"></a>Example 5: Avoiding translatable attribute values</div><p>It is bad design to use the <code>desc</code> attribute to store the alternate descriptive text for the <code>image</code> element, as in this example.</p><div class="exampleInner"><pre>&lt;image src="elephants.png" desc="Elephants bathing in the Zambezi River."/&gt;</pre></div><p>Instead, define the content of <code>image</code> itself to hold the text you need. This way there is no translatable text in an attribute.</p><div class="exampleInner"><pre>&lt;image src="elephants.png"&gt;Elephants bathing in the Zambezi River.&lt;/image&gt;</pre></div></div><div class="note"><p><span class="note-head">Note: </span>In many cases, using translatable element content instead of translatable attributes will result in one sentence being embedded within another one. For instance, in <a class="example-ref" href="#dev-attr-1">Example 5</a> the description of the image will be embedded inside the text of the paragraph that contains it. In such cases, do not forget to declare the relevant element (here <code>image</code>) as 'nested', as described in <a class="technique-ref" href="#DevSeg">Best Practice 6: Providing 
		information related to text segmentation</a>.</p></div><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with an existing  schema where there are attributes with translatable values, you should <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to specify what attributes are translatable. See <a class="technique-ref" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a> for more information about how to do this.</p><p><strong>Why do this</strong></p><p>There are a number of issues related to storing translatable text in attribute values. Some of them are:</p><ul><li><p>The language identification mechanism (i.e. <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>) applies to both the content and to the attribute values of the element where it is declared. If the text of an attribute is in a different language than the text of the element content, one cannot set the language for both correctly.</p></li><li><p>It may be necessary to apply some language-related properties, such as directionality and language identification, to only part of the text in an attribute value. This requires the use of a <code>span</code>-like element, but elements cannot be used within an attribute value.</p></li><li><p>It is difficult to apply meta-information, such as no-translate flags, author's notes, etc., to the text of an  attribute value </p></li><li><p>The difficulty of attaching  unique identifiers to translatable attribute text makes it more complicated to use ID-based leveraging tools.</p></li><li><p>It can be problematic to prepare translatable attributes for localization because they can occur within the content of a translatable element, breaking it into different parts, and possibly altering the sentence structure.</p></li></ul><p>All these potential problems are less likely to occur when the text is the content of an element rather than the value of an attribute.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e1014" name="BId4e1014">Background information</a></h4><ul><li>"Attributes and translatable text" in "Requirements for Localizable DTD Design"<br/> <a href="http://people.w3.org/rishida/localizable-dtds/#attributes">http://people.w3.org/rishida/localizable-dtds/#attributes</a></li></ul><h4><a id="RLd4e1014" name="RLd4e1014">Reference links</a></h4><ul><li>The "Translate" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat</a></li><li>The "Element Within Text" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text">http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1014" name="Rd4e1014">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevTrans" name="DevTrans" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a></div><div class="rule">Document in an ITS Rules document which  elements and attributes need to be translated, and which
				do not, when this differs from the ITS defaults.</div><div class="description"><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to address this requirement.</p><p><strong>How to do this</strong></p><p><a href="#DevITSRules">Provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> elements to indicate which elements have non-translatable content.</p><p>If you are working with a schema where there are translatable attributes (<a href="#DevAttributes">something that is not recommended</a>), you should also use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> to specify these translatable attributes.</p><div class="note"><p><span class="note-head">Note: </span>Where the language of content is given as  <code>xml:lang="zxx"</code>, where <code class="keyword">zxx</code> indicates content that is not in a language, the element in question is probably not to be translated. You should provide a rule for this.</p></div><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devtrans-3" id="EX-devtrans-3"></a>Example 6: Document where default ITS "Translate" rules do not apply</div><p>In the following document, the content of the <code>head</code> element should not be translated, and the value of the <code>alt</code> attribute should be translated. In addition, the content of the <code>del</code> element should not be translated.</p><pre>&lt;myDoc xml:lang='en'&gt;
 &lt;head&gt;
  &lt;id xml:lang="zxx"&gt;H4-A3-F8-A1&lt;/id&gt;
  &lt;author&gt;Robert Griphook&lt;/author&gt;
  &lt;rev&gt;v13 2007-10-27&lt;/rev&gt;
 &lt;/head&gt;
 &lt;par&gt;To start click &lt;ins&gt;the &lt;ui&gt;Start&lt;/ui&gt;
  button&lt;/ins&gt;&lt;del&gt;green icon&lt;/del&gt;
  and fill the form labeled by the following icon:
  &lt;ref file="vat.png" alt="Value Added Tax Form"/&gt;&lt;/par&gt;
&lt;/myDoc&gt;</pre><p>[<a href="EX-devtrans-3.xml">Example's source code</a>]</p><p>The following rules specify exceptions from the default ITS behavior for documents like the one above.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:translateRule selector="/myDoc/head" translate="no"/&gt;
 &lt;its:translateRule selector="//*/@alt" translate="yes"/&gt; 
 &lt;its:translateRule selector="//del" translate="no" /&gt;
 &lt;its:translateRule selector="//@*[ancestor::del]" translate="no"/&gt;
 &lt;its:translateRule selector="//*[lang('zxx')] | //@*[lang('zxx')]" translate="no"/&gt;
&lt;/its:rules&gt;</pre><ul><li><p>First <code>translateRule</code>: The content of <code>head</code> in <code>myDoc</code> is not translatable. By inheritance, the child elements of <code>head</code> are also assumed not translatable.</p></li><li><p>Second <code>translateRule</code>: All the <code>alt</code> attributes are translatable.</p></li><li><p>Third <code>translateRule</code>: The content of <code>del</code> is not translatable.</p></li><li><p>Fourth <code>translateRule</code>: The non-translatability of <code>del</code> applies also to any attribute that may have been set as translatable by a prior rule (i.e. the second rule).</p></li><li><p>Fifth <code>translateRule</code>: Any element or attribute with their language set to <code>zxx</code> is not translatable.</p></li></ul><p>[<a href="EX-devtrans-4.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>By default, ITS assumes that the content of all elements is translatable and that all attributes have non-translatable values. If your XML document type does not correspond to this default assumption it is important to indicate what are the exceptions. Doing so can significantly improve translation throughput.</p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e1160" name="RLd4e1160">Reference links</a></h4><ul><li>The "Translate" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1160" name="Rd4e1160">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevTransOver" name="DevTransOver" href="#DevTransOver">Best Practice 5: Defining markup to override translate information</a></div><div class="rule">Provide a way for authors to override translate defaults, using ITS markup, or document equivalent legacy markup in
			an ITS Rules document.</div><div class="description"><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute and the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to address this requirement.</p><p><strong>How to implement this as a new feature</strong></p><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute is defined for the root element of your documents, and for any element that has text content.</p><p>For examples of how to add attributes in your existing schema see <a class="section-ref" href="#generic_insertatt">Section 4.2: Example of adding an attribute to an existing schema</a>.</p><p>It is also recommended that you  define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one, and within that the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element. Content authors can then use these elements to globally change the default translate rules for specific elements and attributes.</p><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with a schema where there is a way to override translate information that is not <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code>, the authors of the documents should use it. In addition, you should <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element to associate this mechanism with the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>.</p><p>For example, DITA offers a <code>translate</code> attribute, and <a href="#gladebib">Glade</a> provides a <code>translatable</code> attribute. Both have the same semantics as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code>, ie.  the translation information applies to element content, including child elements, but excluding attribute values.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devtransover-2" id="EX-devtransover-2"></a>Example 7: DITA translation information</div><p>The following rules indicate how to associate the DITA <code>translate</code> attribute with the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>. The order in which the rules are listed is important:</p><ul><li><p>First <code>translateRule</code>: Indicates that the content of any element with a <code>translate</code> attribute set to <code>no</code> is not translatable.</p></li><li><p>Second <code>translateRule</code>: Indicates that any attribute value of any element with a <code>translate</code> attribute set to <code>no</code> is not translatable. This is needed because some attributes are translatable in DITA and we need to make sure they are not translated when <code>translate="no"</code> is used in the elements where they are.</p></li><li><p>Third <code>translateRule</code>: Indicates that the content of any element with a <code>translate</code> attribute set to <code>yes</code> is translatable. This takes care of the cases where <code>translate="yes"</code> is used to override a prior <code>translate="no"</code>.</p></li></ul><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:translateRule selector="//*[@translate='no']" translate="no"/&gt;
 &lt;its:translateRule selector="//*[@translate='no']/descendant-or-self::*/@*"
  translate="no"/&gt;
 &lt;its:translateRule selector="//*[@translate='yes']" translate="yes"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devtransover-2.xml">Example's source code</a>]</p><p>You can find a more complete example of how DITA markup is associated with ITS in <a class="section-ref" href="#dita-its-relating">Section 5.4.2: Associating existing DITA markup with ITS</a>.</p></div><p><strong>Why do this</strong></p><p>In some cases, the author of a document may need to change the translatability property on parts of the content, overriding ITS default behavior, or the general rules for the schema that you have specified when applying <a class="technique-ref" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a>.</p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e1317" name="RLd4e1317">Reference links</a></h4><ul><li>The "Translate" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1317" name="Rd4e1317">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevSeg" name="DevSeg" href="#DevSeg">Best Practice 6: Providing 
		information related to text segmentation</a></div><div class="rule">Document in an ITS Rules document how elements should be handled with regard to segmentation.</div><div class="description"><p>Segmentation refers to how text is broken down, from a linguistic viewpoint, into units that can be handled by processes such as translation.</p><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text">ITS Element Within Text data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#withinTextRule">its:withinTextRule</a></code> element to address this requirement.</p><p><strong>How to do this</strong></p><p>Whether you are creating a new schema or documenting legacy markup, <a href="#DevITSRules">provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#withinTextRule">its:withinTextRule</a></code> elements to indicate which elements should be treated as either part of their parents, or as a nested but independent run of text. By default, element boundaries are assumed to correspond to segmentation boundaries.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devseg-1" id="EX-devseg-1"></a>Example 8: A DITA document with formatting and footnote elements.</div><p>In the following DITA document:</p><ul><li><p>The elements <code>term</code> and <code>b</code> should be treated as part of their parent.</p></li><li><p>The element <code>fn</code> should be treated as an  independent run of text.</p></li></ul><pre>&lt;concept id="myConcept" xml:lang="en-us"&gt;
 &lt;title&gt;Types of horse&lt;/title&gt;
 &lt;conbody&gt;
  &lt;ol&gt;
   &lt;li&gt;Palouse horse:&lt;p&gt;&lt;term&gt;Palouse horses&lt;/term&gt;&lt;fn&gt;A palouse horse
    is the same as an &lt;b&gt;Appaloosa&lt;/b&gt;.&lt;/fn&gt; have spotted coats.
    The &lt;term&gt;Nez-Perce&lt;/term&gt; Indians have been key in breeding this
    type of horse.&lt;/p&gt;&lt;/li&gt;
  &lt;/ol&gt;
 &lt;/conbody&gt;
&lt;/concept&gt;</pre><p>[<a href="EX-devseg-1.xml">Example's source code</a>]</p><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#withinTextRule">its:withinTextRule</a></code> element is used to specify the behavior of three elements, all other elements are assumed to have the value <code>its:withinText="no"</code>:</p><ul><li><p>First <code>withinTextRule</code>: The elements <code>term</code> and <code>b</code> are defined as part of the text flow.</p></li><li><p>Second <code>withinTextRule</code>: The element <code>fn</code> is defined as a separate bit of content nested inside its parent element.</p></li></ul><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:withinTextRule selector="//term | //b" withinText="yes"/&gt;
 &lt;its:withinTextRule selector="//fn" withinText="nested"/&gt;
&lt;/its:rules&gt;</pre><p>These rules applied to the DITA document above will result in four distinct runs of text:</p><ol class="depth1"><li><p><code>title: "Types of horse"</code></p></li><li><p><code>li: "Palouse horse:"</code></p></li><li><p><code>p: "{term}Palouse horses{/term}{fn/} have spotted coats. The {term}Nez-Perce{/term} Indians have been key in breeding this type of horse."</code></p></li><li><p><code>fn: "A palouse horse is the same as an {b}Appaloosa{/b}."</code></p></li></ol><p>[<a href="EX-devseg-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>Many applications that process content for linguistic-related tasks need to be able to perform a basic segmentation of the text content. They need to be able to do this without knowing the semantics of the elements.</p><p>While in many cases it is possible to  detect mixed content automatically, there are some situations where the structure of an element makes it impossible for tools to know for sure where appropriate segmentation boundaries fall. For example, the boundaries of some inline elements, such as emphasis, do not typically correspond to segmentation boundaries; on the other hand, some inline elements embedded in a parent element, such as footnotes or quotations, may define segments that should be handled separately from the text in which they are embedded.</p><p>Intelligent segmentation is particularly important in translation to successfully match source text against translation-memory databases. </p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e1446" name="RLd4e1446">Reference links</a></h4><ul><li>The "Element Within Text" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text">http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1446" name="Rd4e1446">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevRuby" name="DevRuby" href="#DevRuby">Best Practice 7: Defining markup for  ruby text</a></div><div class="rule">Provide a way for authors to mark up ruby text using ITS markup, or document equivalent legacy markup in an
			ITS Rules document.</div><div class="description"><p>Ruby text is used to provide a short annotation of an associated base text. It is most often used to provide a reading (pronunciation) guide.</p><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby-annotation">ITS Ruby data category</a> provides the elements <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule">its:rubyRule</a></code> and their children to address this requirement. The definition of this data category is compliant with the specification of Ruby in <a title="Ruby Annotation" href="#rubyan">[Ruby Annotation]</a>.</p><p><strong>How to implement this as a new feature</strong></p><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> element and its children are defined for all elements where there is text content.</p><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with an existing schema where there is a way to specify ruby text that has the same semantics as the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby-annotation">ITS Ruby data category</a> (for example the <cite>Ruby Annotation</cite> <a title="Ruby Annotation" href="#rubyan">[Ruby Annotation]</a>), you should <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule">its:rubyRule</a></code> element to associate your ruby markup with its equivalent in ITS.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devruby-1" id="EX-devruby-1"></a>Example 9: Document with ruby-like elements.</div><p>In this document, the <code>rubyBlock</code> element has the same functionality as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code>, <code>rBase</code> as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rb">its:rb</a></code>, <code>rParen</code> as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rp">its:rp</a></code>, and <code>rText</code> as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rt">its:rt</a></code>.</p><pre>&lt;text&gt;
 &lt;para&gt;この本は &lt;rubyBlock&gt;
  &lt;rBase&gt;慶応義塾大学&lt;/rBase&gt;
  &lt;rParen&gt;(&lt;/rParen&gt;
  &lt;rText&gt;けいおうぎじゅくだいがく&lt;/rText&gt;
  &lt;rParen&gt;)&lt;/rParen&gt;
 &lt;/rubyBlock&gt;の歴史を説明するものです。&lt;/para&gt;
&lt;/text&gt;</pre><p>[<a href="EX-devruby-1.xml">Example's source code</a>]</p><p>This <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule">its:rubyRule</a></code> element indicates that the <code>rBase</code> element has the same functionality as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rb">its:rb</a></code> and that the elements <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rt">its:rt</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rt">its:rt</a></code> have equivalent elements as well.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:rubyRule selector="//rBase" rubyPointer=".."
  rpPointer="../rParen" rtPointer="../rText" /&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devruby-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>Ruby is a type of annotation for text. It can be used with any language, but is very commonly used with East Asian scripts to provide phonetic transcriptions of characters that are likely to be unfamiliar to a reader. For example it is widely used in educational materials and children’s texts. It is also occasionally used to convey information about meaning.</p><p>Because ruby annotation may be needed when localizing into Japanese or Chinese, it is a good idea to make provision for it in your schema, even if your original documents are to be developed into a language that does not use such markup.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e1584" name="BId4e1584">Background information</a></h4><ul><li>Internationalization FAQ: Ruby<br/> <a href="http://www.w3.org/International/questions/qa-ruby">http://www.w3.org/International/questions/qa-ruby</a></li><li>"Implementing the Ruby Module", a personal note.<br/> <a href="http://www.w3.org/People/mimasa/test/schemas/NOTE-ruby-implementation">http://www.w3.org/People/mimasa/test/schemas/NOTE-ruby-implementation</a></li></ul><h4><a id="RLd4e1584" name="RLd4e1584">Reference links</a></h4><ul><li>The "Ruby" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby-annotation">http://www.w3.org/TR/2007/REC-its-20070403/#ruby-annotation</a></li><li>Ruby Annotation<br/> <a href="http://www.w3.org/TR/ruby/">http://www.w3.org/TR/ruby/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1584" name="Rd4e1584">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevLocNote" name="DevLocNote" href="#DevLocNote">Best Practice 8: Defining markup for  notes to localizers</a></div><div class="rule">Provide a way for authors to specify notes for localizers using ITS markup, or document equivalent legacy markup in an ITS Rules
			document.</div><div class="description"><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote-datacat">ITS Localization Note data category</a> provides the attributes <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code>, as well as the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element to address this requirement.</p><p><strong>How to implement this as a new feature</strong></p><p>Make sure the attributes <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> are defined in your schema. This markup allows content authors to provide localization-related notes as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute values, or to point to the location of the relevant note text using <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code>.</p><p>For examples of how to add attributes in your existing schema see <a class="section-ref" href="#generic_insertatt">Section 4.2: Example of adding an attribute to an existing schema</a>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devlocnotes-1" id="EX-devlocnotes-1"></a>Example 10: An illustration of how an author could point to  localization notes with <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></div><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote">its:locNote</a></code> element specifies that the message with the identifier <code>NotFound</code> has a corresponding explanation note in an external HTML file. The URI for the exact location of the note is stored in the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> attribute.</p><pre>&lt;myRes&gt;
 &lt;head&gt;
  &lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
   &lt;its:locNoteRule locNoteType="description"
    selector="//msg[@id='NotFound']"
    locNoteRef="EX-devlocnotes-4.html#NotFound" /&gt;
  &lt;/its:rules&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;msg id="NotFound"&gt;Cannot find {0} on {1}.&lt;/msg&gt;
 &lt;/body&gt;
&lt;/myRes&gt;</pre><p>[<a href="EX-devlocnotes-4.xml">Example's source code</a>]</p><p>The HTML file with the localization notes is a simple document with the anchor elements corresponding to the identifiers in the referring XML document.</p><pre>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
&lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"&gt; 
 &lt;head&gt;
  &lt;meta http-equiv="Content-Language" content="en-us"&gt;
  &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt; 
  &lt;title&gt;Localization Notes&lt;/title&gt;
 &lt;/head&gt; 
 &lt;body lang="en"&gt;
 &lt;p&gt;&lt;a name="NotFound"&gt;&lt;/a&gt;{0} is a filename&lt;br /&gt;
  {1} is a directory name&lt;/p&gt;
 &lt;/body&gt;
&lt;/html&gt; 
</pre><p>[<a href="EX-devlocnotes-4.html">Example's source code</a>]</p></div><p>It is also recommended that you  define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one, and within that the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element and its related markup. Content authors  can use this markup to specify localization-related notes. Within the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element, notes can be stored in the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote">its:locNote</a></code> element.</p><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element also allows you to specify notes in the current XML document via the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule.attributes">locNotePointer</a></code> attribute, or to provide an existing reference to notes via the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule.attributes">locNoteRefPointer</a></code> attribute.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devlocnotes-2" id="EX-devlocnotes-2"></a>Example 11: An illustration of how an author could store  localization notes in  <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code></div><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element associates the content of the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote">its:locNote</a></code> element with the message that has the identifier 'DisableInfo', and flags it as important. This would also work if the rule was in an external file, allowing content authors to provide notes without modifying the source document.</p><pre>&lt;myDoc&gt;
 &lt;head&gt;
  &lt;its:rules xmlns:its="http://www.w3.org/2005/11/its"
   version="1.0" its:translate="no"&gt;
   &lt;its:locNoteRule locNoteType="alert" selector="//msg[@id='DisableInfo']"&gt;
   &lt;its:locNote&gt;The variable {0} has three possible values: 'printer',
    'stacker' and 'stapler options'.&lt;/its:locNote&gt;
   &lt;/its:locNoteRule&gt;
  &lt;/its:rules&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;msg id="DisableInfo"&gt;The {0} has been disabled.&lt;/msg&gt;
 &lt;/body&gt;
&lt;/myDoc&gt;</pre><p>[<a href="EX-devlocnotes-3.xml">Example's source code</a>]</p><div class="note"><p><span class="note-head">Note: </span>The example includes <code>its:translate="no"</code> in the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> tag, to prevent translators from attempting to translate the notes themselves.</p></div></div><p>Storing notes as element content has advantages over storing notes as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute values: markup for such things as <a href="#DevLang">language</a> and <a href="#DevDir">directionality</a> can be associated with the text of the content of an element, or parts of the text when a <a href="#DevSpan">span-like element</a> is also available, but you cannot do these things with attribute text.</p><p>Storing notes in an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote">its:locNote</a></code> element can therefore offer these advantages as long as there is a mechanism to associate the notes with the relevant content.  On the other hand, it can be easier to scan documents, in some cases, if the note text is stored in elements or attributes alongside the content it refers to.</p><p>Although ITS provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute to store note text, offering the possibility of closely associating the note with the relevant content, using this approach makes it difficult to annotate the notes themselves for language, directionality, etc.</p><p>It can be argued that notes, being metadata, have different requirements to the content itself. Schema developers should carefully consider which approach to use. If all notes will always be written by English-speaking content developers, it may be acceptable to use attribute values, but if notes may be written by content developers in Arabic or Hebrew, they are almost certainly going to want to use directional markup and span elements in the notes themselves, so an element-based approach would almost certainly be better.</p><p><strong>Handling markup not in the ITS namespace</strong></p><p>If you are working with an existing schema where there is a way to provide notes to the localizers that is not implemented using ITS, you should <a href="#DevITSRules">provide an ITS Rules document</a> where you use the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element to associate your notes markup with its equivalent in ITS.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devlocnotes-3" id="EX-devlocnotes-3"></a>Example 12: Document with custom localization notes</div><p>In this document the <code>comment</code> element is a note for its sibling <code>text</code> element.</p><pre>&lt;messages&gt;
 &lt;msg id="ERR_NOFILE"&gt;
  &lt;text&gt;The file '{0}' could not be found.&lt;/text&gt;
  &lt;comment&gt;The variable {0} is the name of a file.&lt;/comment&gt; 
 &lt;/msg&gt;
&lt;/messages&gt;</pre><p>[<a href="EX-devlocnotes-1.xml">Example's source code</a>]</p><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule">its:locNoteRule</a></code> element specifies that the <code>text</code> elements have an associated localization description in their sibling <code>comment</code> elements.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:locNoteRule selector="//msg/text" locNoteType="description"
  locNotePointer="../comment"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devlocnotes-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>To assist the translator to achieve a correct translation, authors may need to provide information about the text that they have written. For example, the author may want to do the following:</p><ul><li><p>Tell the translator how to translate part of the content (e.g. "Leave text in uppercase").</p></li><li><p>Expand on the meaning or contextual usage of a particular element, such as what a variable refers to or how a string will be used on the UI.</p></li><li><p>Clarify ambiguity and show relationships between items sufficiently to allow correct translation (e.g. in many languages it is impossible to translate the word 'enabled' in isolation without knowing the gender, number and case of the thing it refers to.)</p></li><li><p>Explain why text is not to be translated, point to text reuse, or describe the use of conditional text.</p></li><li><p>Indicate why a piece of text is emphasized (important, sarcastic, etc.)</p></li></ul></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e1857" name="RLd4e1857">Reference links</a></h4><ul><li>The "Localization Note" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNote-datacat">http://www.w3.org/TR/2007/REC-its-20070403/#locNote-datacat</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1857" name="Rd4e1857">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevUniqueID" name="DevUniqueID" href="#DevUniqueID">Best Practice 9: Defining markup for  unique identifiers</a></div><div class="rule">Provide a way for authors to assign unique identifiers to localizable elements.</div><div class="description"><p><strong>How to do this</strong></p><p>Make sure that elements with translatable content can be associated with a unique identifier.</p><p>It is strongly recommended that you define such identifiers as attributes of type ID, following the rules described in <cite>xml:id Version 1.0</cite> <a title="xml:id Version 1.0" href="#xmlid">[xml:id]</a>. This allows XML applications to take advantage of the built-in processes associated with that datatype, such as validation.</p><p>It is also recommended that you  name such attributes <code><a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">xml:id</a></code> to increase interoperability.</p><div class="note"><p><span class="note-head">Note: </span> Unique identifiers are most useful when their values are <em>globally unique</em> (i.e. unique across any documents) and <em>persistent</em> (i.e. ones which do not change over time). </p></div><p><strong>Why do this</strong></p><p>In order to most effectively reuse translated text where content is reused (for example across updates) it is necessary to have a unique and persistent identifier associated with the element.</p><p>This identifier allows the translation tools to correctly track an item from one version or location to the next. After ensuring that this is the same item, the content can be examined for changes, and if no change has taken place the potential for reuse of the previous translation is very high.</p><p>Change analysis of this kind constitutes an extremely powerful productivity tool for translation when compared to typical source matching techniques (a.k.a. translation memory). These techniques simply look for similar source text in a multilingual database without, most of the time, being able to tell whether the context of its use is the same.</p><p>Identifiers can also be helpful to track displayed text back to its underlying source. For example, when reviewing a translated user interface, the identifiers can be used as temporary prefixes to the text so that any correction can be efficiently done on the proper strings.</p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e1908" name="RLd4e1908">Reference links</a></h4><ul><li>W3C Recommendation: xml:id<br/> <a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">http://www.w3.org/TR/2005/REC-xml-id-20050909/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e1908" name="Rd4e1908">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevTerm" name="DevTerm" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a></div><div class="rule">Document in an ITS Rules document what elements are related to terms and term-related information.</div><div class="description"><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">ITS Terminology data category</a> provides the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> element to address this requirement.</p><p><strong>How to do this</strong></p><p><a href="#DevITSRules">Provide an ITS Rules document</a> where you use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> elements to indicate which elements are terms and information related to them (e.g. definitions).</p><div class="note"><p><span class="note-head">Note: </span>The information identified through the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> can be of any type (e.g. human-readable or machine-specific). It is up to the application processing the data to make the distinction.</p></div><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devterm-1" id="EX-devterm-1"></a>Example 13: Document with terminology-related elements</div><p>In this document, the elements <code>term</code> and <code>dt</code>, as well as any element with a <code>syn</code> attribute, denote terms. In addition, they can all have associated information.</p><pre>&lt;myDoc&gt;
 &lt;body&gt;
  &lt;p&gt;A &lt;term def="d001" syn="#alterego"&gt;doppelgänger&lt;/term&gt;
  is basically &lt;def xml:id="d001"&gt;the counterpart of a 
  person&lt;/def&gt;. It is almost the same as an 
  &lt;emph syn="#alterego"&gt;alter ego&lt;/emph&gt;, but with a more sinister
  connotation. Sometimes the word &lt;emph syn="#alterego"&gt;fetch&lt;/emph&gt;
  is also used.&lt;/p&gt;
 &lt;/body&gt;
 &lt;definitions&gt;
  &lt;entry xml:id="alterego"&gt;
   &lt;dt&gt;alter ego&lt;/dt&gt;
   &lt;dd&gt;A second self. Figurative sense: trusted friend.&lt;/dd&gt;
   &lt;origin&gt;Latin, literally: "second I"&lt;/origin&gt;
  &lt;/entry&gt;
 &lt;/definitions&gt;
&lt;/myDoc&gt;</pre><p>[<a href="EX-devterm-1.xml">Example's source code</a>]</p><p>The set of ITS rules below indicates:</p><ul><li><p>First <code>termRule</code>: The <code>term</code> element is a term and its associated information can be accessed in the node that has the identifier corresponding to the value in its <code>def</code> attribute.</p></li><li><p>Second <code>termRule</code>: Any element with a <code>syn</code> attribute is considered a term and the <code>syn</code> attribute contains a URI location where some associated information can be found.</p></li><li><p>Third <code>termRule</code>: The <code>dt</code> element is a term and its associated information is in its sibling element <code>dd</code>.</p></li></ul><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:termRule selector="//term" term="yes" termInfoPointer="id(@def)"/&gt;
 &lt;its:termRule selector="//*[@syn]" term="yes" termInfoRefPointer="@syn"/&gt;
 &lt;its:termRule selector="//dt[../dd]" term="yes" termInfoPointer="../dd"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devterm-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>The capability of specifying terms within the source content is important for terminology management and beneficial to translation and localization quality. For example, term identification facilitates the creation of glossaries and allows the validation of terminology usage in the source and translated documents.</p><p>Term identification is also useful for change management and to ensure source language quality.</p><p>Terms may require various associated information, such as part of speech, gender, number, term types, definitions, notes on usage, etc. To avoid associated information to be repeated throughout a document, it should be possible for identified terms to link to externalized attribute data, such as glossary documents and terminology database.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e2024" name="BId4e2024">Background information</a></h4><ul><li>"Markup and Terminological Databases" in the Cover Pages<br/> <a href="http://xml.coverpages.org/terminology.html">http://xml.coverpages.org/terminology.html</a></li><li>"Saving Money Through Terminology Management", article.<br/> <a href="http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html">http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html</a></li></ul><h4><a id="RLd4e2024" name="RLd4e2024">Reference links</a></h4><ul><li>The "Terminology" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">http://www.w3.org/TR/2007/REC-its-20070403/#terminology</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2024" name="Rd4e2024">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevTermOver" name="DevTermOver" href="#DevTermOver">Best Practice 11: Defining markup for specifying or overriding terminology-related information</a></div><div class="rule">Provide a way for authors to specify or override terminology-related information using ITS markup, or document equivalent legacy markup in
			an ITS Rules document.</div><div class="description"><p>The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">ITS Terminology data category</a> provides the attributes <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code>, as well as the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> element to address this requirement.</p><p><strong>How to do this</strong></p><p>Make sure the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> attributes are defined for any element that has text content.</p><p>For examples of how to add attributes in your existing schema see <a class="section-ref" href="#generic_insertatt">Section 4.2: Example of adding an attribute to an existing schema</a>.</p><p>It is also recommended to define the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element in your schema, for example in a header if there is one. The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element provides access to the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> element which can be used to override terminology-related information globally.</p><p><strong>Why do this</strong></p><p>In some cases, the author of a document may need to change the information indicating what is a term or how to point to term information, overriding the general rules for the schema that you have specified when applying <a class="technique-ref" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a>.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e2102" name="BId4e2102">Background information</a></h4><ul><li>"Markup and Terminological Databases" in the Cover Pages<br/> <a href="http://xml.coverpages.org/terminology.html">http://xml.coverpages.org/terminology.html</a></li><li>"Saving Money Through Terminology Management", article.<br/> <a href="http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html">http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html</a></li></ul><h4><a id="RLd4e2102" name="RLd4e2102">Reference links</a></h4><ul><li>The "Terminology" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">http://www.w3.org/TR/2007/REC-its-20070403/#terminology</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2102" name="Rd4e2102">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevMLDoc" name="DevMLDoc" href="#DevMLDoc">Best Practice 12: Working with multilingual documents</a></div><div class="rule">Avoid document formats that store multiple localized versions of content within the same document.</div><div class="description"><p>This best practice refers specifically to situations where copies of the same content are stored  in multiple languages in a single document. It is perfectly acceptable to have multilingual text in a document otherwise.</p><p><strong>How to do this</strong></p><p>For documents that need to go through some localization tasks, always store  the localized version of the text in a separate document.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devmldoc-1" id="EX-devmldoc-1"></a>Example 14: Avoiding multilingual documents</div><p>This is an example of bad design. It shows a single document that contains multiple translations of the same content:</p><pre>&lt;messages&gt;
 &lt;msg xml:id='fileNotFound'&gt;
  &lt;text xml:lang="en"&gt;File not found.&lt;/text&gt;
  &lt;text xml:lang="fr"&gt;Fichier non trouvé.&lt;/text&gt;
 &lt;/msg&gt;
&lt;/messages&gt;</pre><p>[<a href="EX-devmldoc-1.xml">Example's source code</a>]</p><p>Instead, use one document for each language. Here one in English, and the other one in French. Other languages would go in similar separate documents.</p><pre>&lt;messages xml:lang="en"&gt;
 &lt;msg xml:id='fileNotFound'&gt;
  &lt;text&gt;File not found.&lt;/text&gt;
 &lt;/msg&gt;
&lt;/messages&gt;
</pre><p>[<a href="EX-devmldoc-2.xml">Example's source code</a>]</p><pre>&lt;messages xml:lang="fr"&gt;
 &lt;msg xml:id='fileNotFound'&gt;
  &lt;text&gt;Fichier non trouvé.&lt;/text&gt;
 &lt;/msg&gt;
&lt;/messages&gt;
</pre><p>[<a href="EX-devmldoc-3.xml">Example's source code</a>]</p></div><div class="note"><p><span class="note-head">Note: </span>It is admissible to store multilingual copies of a content in a single document <strong>before</strong> the document to send to localization, or <strong>after</strong> all localization tasks are done. For example, a final resource file could be constructed by collating the different language entries.</p></div><div class="note"><p><span class="note-head">Note: </span>It is admissible to provide the localizer with multilingual documents in XML formats that are specifically designed for localization, and are industry standards, like the <span xml:lang="en-gb" lang="en-gb">XML Localisation Interchange File Format</span> <a title="XLIFF Version 1.2 XLIFF 1.2" href="#xliff12">[XLIFF 1.2]</a>.</p></div><p><strong>Why do this</strong></p><p>There are two main reasons to avoid sending documents for localization if the source material is located in parallel with the different translations in the same document:</p><ol class="depth1"><li><p>It is difficult to manage concurrent translations in all languages. It is very likely that each translation will be done by a different translator, in a different location.  To facilitate this, the document will have to be broken down into separate parts and reconstructed later on. This adds processing time, increases cost and provides more opportunities for the introduction of errors.</p></li><li><p>Depending on the point in the document's lifecycle, such a document may already contain translations, some up-to-date and some outdated (because the source material may have changed). In order to identify what parts need to be localized and what parts should be left alone, the document would  then also need to contain custom information about localization state, which may or may not be supported by localization tools.</p></li></ol></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevElemNames" name="DevElemNames" href="#DevElemNames">Best Practice 13: Naming elements and attributes</a></div><div class="rule">Use a meaningful and non-dynamic naming scheme for your elements and attributes.</div><div class="description"><p><strong>How to do this</strong></p><p>Make sure the names of the elements and attributes of your schema reflect their functions, rather than one possible way of rendering their content.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-develemnames-1" id="EX-develemnames-1"></a>Example 15: Using meaningful names</div><p>This is an  example of bad design. The element <code>b</code> is used for several purposes.</p><pre>&lt;doc&gt;
 &lt;p&gt;To run the application, click the &lt;b&gt;Start&lt;/b&gt; button.&lt;/p&gt;
 &lt;p&gt;&lt;b&gt;Make sure to enter your username&lt;/b&gt;, and then
  press &lt;b&gt;OK&lt;/b&gt;.&lt;/p&gt;
&lt;/doc&gt;</pre><p>[<a href="EX-develemnames-1.xml">Example's source code</a>]</p><p>Instead, define different elements based on their functions rather than a pre-supposed rendering.</p><pre>&lt;doc&gt;
 &lt;p&gt;To run the application, click the &lt;ui&gt;Start&lt;/ui&gt; button.&lt;/p&gt;
 &lt;p&gt;&lt;emph&gt;Make sure to enter your username&lt;/emph&gt;, and then
  press &lt;ui&gt;OK&lt;/ui&gt;.&lt;/p&gt;
&lt;/doc&gt;</pre><p>[<a href="EX-develemnames-2.xml">Example's source code</a>]</p></div><p>Also, if possible, avoid element names which do not follow a fixed naming scheme (for example, element names that serve also as identifiers).</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-develemnames-3" id="EX-develemnames-3"></a>Example 16: Avoid dynamic names</div><p>This is an  example of bad design. The names of the elements also serve as text identifiers.</p><pre>&lt;strings&gt;
 &lt;str1&gt;Input path:&lt;/str1&gt;
 &lt;str2&gt;Help&lt;/str2&gt;
 &lt;str3&gt;OK&lt;/str3&gt;
 &lt;str4&gt;Cancel&lt;/str4&gt;
&lt;/strings&gt;</pre><p>[<a href="EX-develemnames-3.xml">Example's source code</a>]</p><p>Instead, use elements names that follow a fixed naming scheme, and use <code><a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">xml:id</a></code> for the identifiers.</p><pre>&lt;strings&gt;
 &lt;str xml:id="str1"&gt;Input path:&lt;/str&gt;
 &lt;str xml:id="str2"&gt;Help&lt;/str&gt;
 &lt;str xml:id="str3"&gt;OK&lt;/str&gt;
 &lt;str xml:id="str4"&gt;Cancel&lt;/str&gt;
&lt;/strings&gt;</pre><p>[<a href="EX-develemnames-4.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>The name of an element should indicate what its function is, not how its content will be presented, because presentation may vary depending on different factors such as language, script, medium, or accessibility.</p><p>Using documents where elements or attributes do not follow a predictable naming pattern may cause problems when using XSLT-driven processes. It may also be an issue for translation tools. This is especially true if not all parts of the document are to be translated, since it would be more difficult to specify  rules to distinguish the translatable nodes from the non-translatable ones.</p></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevSpan" name="DevSpan" href="#DevSpan">Best Practice 14: Defining a span-like element</a></div><div class="rule">Provide a way for authors to annotate arbitrary content using its:span or equivalent markup.</div><div class="description"><p>A <code>span</code>-like element is an element that can be used to mark up arbitrary content and associate it with various properties such as directionality or language information. Examples of such an element include the <code>span</code> element in XHTML, or the <code>phrase</code> element in DocBook.</p><p><strong>How to do this</strong></p><p>Make sure you define a <code>span</code>-like element in your schema that will allow authors to associate arbitrary content with  properties such as directionality, language information, etc.</p><p>If your schema does not already provide such an element, you could provide the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code> element.</p><p> The definition of the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code> element in the ITS Specification lists a set of ITS attributes that should be allowed on a span-like element.</p><p><strong>Why do this</strong></p><p>Some properties of content are applied using attributes. Directionality, terminology, localization notes, translate information, and language identification are examples of such properties. There is a need for a neutral element to delimit the run of text to which such attributes apply, since the appropriate boundaries are sometimes not delimited by other markup that is present, or perhaps those attributes are not permitted on other markup that is present.</p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e2297" name="RLd4e2297">Reference links</a></h4><ul><li>W3C Recommendation: Internationalization Tag Set (ITS)<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/">http://www.w3.org/TR/2007/REC-its-20070403/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2297" name="Rd4e2297">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="DevITSRules" name="DevITSRules" href="#DevITSRules">Best Practice 15: Documenting internationalization and localization features of your schema</a></div><div class="rule">Provide an ITS Rules document containing  all the ITS rules needed to interpret legacy markup,
				and identify translate, terminology and text segmentation information in your format.</div><div class="description"><p><strong>How to do this</strong></p><p>Make sure you document the internationalization and localization aspects of your schema by providing a set of relevant ITS rules in a single standalone ITS Rules document.</p><p>Your ITS Rules document should include the following information, when applicable:</p><ul><li><p>The correspondence between any proprietary mechanism you have to specify the language of content and <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> (see <a class="technique-ref" href="#DevLang">Best Practice 1: Defining markup for natural language labelling</a>).</p></li><li><p>The correspondence between any proprietary mechanism you have to indicate text directionality and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> (see <a class="technique-ref" href="#DevDir">Best Practice 2: Defining markup to specify text direction</a>).</p></li><li><p>What markup has translate rules different from the default expectation that elements are to be translated and attributes are not (see <a class="technique-ref" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a>).</p></li><li><p>The correspondence between any proprietary mechanism you have to override translatability information and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> (see <a class="technique-ref" href="#DevTransOver">Best Practice 5: Defining markup to override translate information</a>).</p></li><li><p>The list of elements that should be treated as "nested" or "within text" from a segmentation viewpoint (see <a class="technique-ref" href="#DevSeg">Best Practice 6: Providing 
		information related to text segmentation</a>).</p></li><li><p>The correspondence between any proprietary mechanism you have to mark up ruby text and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> (See <a class="technique-ref" href="#DevRuby">Best Practice 7: Defining markup for  ruby text</a>).</p></li><li><p>What part of your markup holds notes for the localizers (see <a class="technique-ref" href="#DevLocNote">Best Practice 8: Defining markup for  notes to localizers</a>).</p></li><li><p>What part of your markup denotes terms and term-related information (see <a class="technique-ref" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a>).</p></li></ul><p>You can find some examples of ITS Rules documents for existing XML formats in <a class="section-ref" href="#Modularization">Section 5: ITS Applied to Existing Formats</a>.</p><p><strong>Why do this</strong></p><p>Although some XML vocabularies are easy to understand or process, it is often helpful or necessary to provide explicit information about a given vocabulary. If such a vocabulary is to be used in a multilingual context, it is of high importance to provide  information, such as which elements contain translatable content, because general information on purpose, general structure, and node types very often are not sufficient. In a way, this need for explicit information is related to the general good practice of documenting source code.</p><p>In XML it should come naturally to use a well-defined, structured format to capture such information. For information related to internationalization and translation, ITS Rules documents are a good choice for the following reasons:</p><ul><li><p>They are designed to take into account many important aspects of internationalization and translation.</p></li><li><p>They capture information precisely (for example, selectors identify to which nodes a data category pertains).</p></li><li><p>They can be processed by ITS-aware applications.</p></li><li><p>They can  be easily combined with additional structured information (e.g. related to version control, as shown in the example below).</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-devitsrules-1" id="EX-devitsrules-1"></a>Example 17: ITS rules embedded in a customized information file</div><p>An ITS processor should still be able to process a file as an external ITS rules file if the format of the file contains your own customized information in addition to the ITS rules.  The following is an example of that.</p><pre>&lt;myFormatInfo xmlns:its="http://www.w3.org/2005/11/its"&gt;
 &lt;desc&gt;ITS rules used by the Open University&lt;/desc&gt;
 &lt;hostVoc&gt;http://www.example.com/ns/myFormat&lt;/hostVoc&gt;
 &lt;rulesId&gt;98ECED99DF63D511B1250008C784EFB1&lt;/rulesId&gt;
 &lt;rulesVersion&gt;v 1.81 2006/03/28 07:43:21&lt;/rulesVersion&gt;
 &lt;its:rules version="1.0"&gt;
  &lt;its:translateRule selector="//header" translate="no"/&gt;
  &lt;its:translateRule selector="//term" translate="no"/&gt;
  &lt;its:termRule selector="//term" term="yes"/&gt;
  &lt;its:withinTextRule withinText="yes" selector="//term|//b"/&gt;
 &lt;/its:rules&gt;
&lt;/myFormatInfo&gt;
</pre><p>[<a href="EX-devitsrules-1.xml">Example's source code</a>]</p></div></li></ul></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e2409" name="RLd4e2409">Reference links</a></h4><ul><li>W3C Recommendation: Internationalization Tag Set (ITS)<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/">http://www.w3.org/TR/2007/REC-its-20070403/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2409" name="Rd4e2409">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div></div><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="AuthoringTime" id="AuthoringTime"></a>3 When Authoring XML Content</h2><p>Authors of XML content should consider the following best practices:</p><a name="AuthSummaryTable" id="AuthSummaryTable"></a><table border="1" cellpadding="5" cellspacing="1"><thead><tr><th>Best Practice</th><th>Summary</th></tr></thead><tbody align="left" valign="top"><tr><td><a class="technique-ref" href="#AuthLang">Specifying the language of content</a></td><td>Use <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> (or its equivalent in your schema) on the root element of the document, and on each element where the language of the content changes.</td></tr><tr><td><a class="technique-ref" href="#AuthDir">Specifying text directionality</a></td><td>By default the text directionality in an XML document is assumed to be left-to-right. Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> (or its equivalent in your schema) on the root element of any document where the text runs predominantly from right-to-left, and on elements where the Unicode bidirectional algorithm needs help to achieve proper display of bidirectional text.</td></tr><tr><td><a class="technique-ref" href="#AuthTransOver">Overriding information about what should be translated</a></td><td>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> (or its equivalent in your schema) on each element for which the translatability property is different from the defaults set for your schema.</td></tr><tr><td><a class="technique-ref" href="#AuthUniqueID">Assigning unique identifiers</a></td><td>Use unique identifiers in the way provided by your schema on each element that constitutes a segmentation boundary. If possible use <em>globally unique</em> and <em>persistent</em> values as identifier values.</td></tr><tr><td><a class="technique-ref" href="#AuthCDATA">Avoiding CDATA sections</a></td><td>Do not put content that will be translated into CDATA sections.</td></tr><tr><td><a class="technique-ref" href="#AuthLocNote">Providing notes for localizers</a></td><td>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> (or their equivalents in your schema) to provide notes to the localizer.</td></tr><tr><td><a class="technique-ref" href="#AuthInsText">Working with inserted text</a></td><td>Use inserted text only when the text is self-contained and does not affect its surrounding context. For example, titles and quotations are inserted text that, usually, would not cause problems. Avoid using inserted text that has any dependence on the context where it is inserted.</td></tr><tr><td><a class="technique-ref" href="#AuthTermOver">Identifying terms</a></td><td>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> (or their equivalent in your schema) to mark terms and supply term-related information.</td></tr><tr><td><a class="technique-ref" href="#AuthMarkupAsText">Storing markup from another format</a></td><td>If possible, use the <a href="#xmlns">XML namespace mechanism</a> to store different vocabularies inside a single XML document.</td></tr></tbody></table><p>A number of these practices can be followed only when the XML application has been internationalized properly using the design guidelines in <a class="section-ref" href="#DesignTime">Section 2: When Designing an XML Application</a>.</p><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthLang" name="AuthLang" href="#AuthLang">Best Practice 16: Specifying the language of content</a></div><div class="rule">Specify the natural language of your content using xml:lang, or an equivalent mechanism provided by your document format.</div><div class="description"><p>Your schema should provide the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute (or an equivalent mechanism) for specifying the language of content. See <a class="technique-ref" href="#DevLang">Best Practice 1: Defining markup for natural language labelling</a> for more information.</p><p><strong>How to do this</strong></p><p>Use <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> (or its equivalent in your schema) on the root element of the document, and on each element where the language of the content changes. The elements without declarations inherit the language information from their parents. Attribute values are deemed to be in the same language as the element where they are declared.</p><p>Make sure the values of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> conform to <cite>Tags for Identifying Languages</cite> <a title="Tags for Identifying Languages" href="#langtag">[BCP 47]</a>. For a brief introduction to how to form language values using BCP 47 see <a href="http://www.w3.org/International/articles/language-tags/">Language tags in HTML and XML</a>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authlang-1" id="EX-authlang-1"></a>Example 18: Declaring language information with <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code></div><p>In this example, the main content of the document is in English, while a short citation in the <code>q</code> element is identified as  French using <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> set to <code>fr</code>.</p><pre>&lt;document xml:lang="en"&gt;
 &lt;para&gt;The motto of Québec is the short phrase:
  &lt;q xml:lang="fr"&gt;Je me souviens&lt;/q&gt;. It is chiseled on 
  the front of the Parliament Building.&lt;/para&gt;
&lt;/document&gt;</pre><p>[<a href="EX-authlang-1.xml">Example's source code</a>]</p></div><p>If the schema you are using does not provide an <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute, use the equivalent attribute.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authlang-2" id="EX-authlang-2"></a>Example 19: Declaring language information with a non-standard mechanism</div><p>In this example, the schema for this document type uses a non-standard way to specify language: a <code>code</code> attribute. Authors should use that mechanism, not <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>, because the developer of the <code>stringList</code> document type should provide, along with the schema, an ITS Rules document (shown below) that declares <code>code</code> to be equivalent to <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> when used with the <code>lang</code> element.</p><pre>&lt;stringList&gt;
 &lt;msg id="connected"&gt;
  &lt;lang code="cs"&gt;Jste připojeni k Internetu.&lt;/lang&gt;
  &lt;lang code="de"&gt;Sie sind an das Netz angeschlossen.&lt;/lang&gt;
  &lt;lang code="fr"&gt;Vouz êtes connecté à la Toile.&lt;/lang&gt;
  &lt;lang code="it"&gt;Sei connesso al Web.&lt;/lang&gt;
  &lt;lang code="ja"&gt;インターネットに接続しました。&lt;/lang&gt;
  &lt;lang code="ko"&gt;웹에 연결되었습니다.&lt;/lang&gt;
  &lt;lang code="ru"&gt;Вы подключены к Интернету.&lt;/lang&gt;
 &lt;/msg&gt;
&lt;/stringList&gt;</pre><p>[<a href="EX-authlang-2.xml">Example's source code</a>]</p><div class="note"><p><span class="note-head">Note: </span>This example is a multilingual document, which has its own set of issues as described in <a class="technique-ref" href="#DevMLDoc">Best Practice 12: Working with multilingual documents</a>.</p></div><p>The developer of the <code>stringList</code> document type should provide an ITS Rules document in compliance with <a class="technique-ref" href="#DevLang">Best Practice 1: Defining markup for natural language labelling</a> for existing schemas. Here the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule">its:langRule</a></code> element defines the <code>code</code> attribute of the <code>lang</code> element to be equivalent to <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:langRule selector="//lang[@code]" langPointer="@code" /&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-authlang-3.xml">Example's source code</a>]</p></div><div class="note"><p><span class="note-head">Note: </span>In some cases, a change in language has implications for translation. For example, content in a different language may have to remain untranslated, or require specific handling. Such information could be provided to the localizer using <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> or <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> (or their equivalents in your schema). For more details, see <a class="technique-ref" href="#AuthTransOver">Best Practice 18: Overriding information about what should be translated</a> and <a class="technique-ref" href="#AuthLocNote">Best Practice 21: Providing notes for localizers</a>.</p></div><p><strong>Why do this</strong></p><p>Knowing the language of the content is very important in many situations. These include:</p><ul><li><p>Selection of a proper font (e.g. for Traditional or Simplified Chinese.)</p></li><li><p>Processing of the text for wrapping and hyphenation.</p></li><li><p>Providing spell-checking or grammar verification of the text.</p></li><li><p>Selecting proper automated selections of text such as quotation marks or other punctuation signs.</p></li><li><p>Using the text with voice browsers.</p></li></ul></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e2687" name="BId4e2687">Background information</a></h4><ul><li>Internationalization FAQ: xml:lang in XML document schemas.<br/> <a href="http://www.w3.org/International/questions/qa-when-xmllang">http://www.w3.org/International/questions/qa-when-xmllang</a></li></ul><h4><a id="RLd4e2687" name="RLd4e2687">Reference links</a></h4><ul><li>BCP 47 - Tags for Identifying Languages.<br/> <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">http://www.rfc-editor.org/rfc/bcp/bcp47.txt</a></li><li>Description of the language identification mechanism in the XML specification.<br/> <a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">http://www.w3.org/TR/REC-xml/#sec-lang-tag</a></li><li>Language tags in HTML and XML.<br/> <a href="http://www.w3.org/International/articles/language-tags/">http://www.w3.org/International/articles/language-tags/</a></li><li>Tagging text with no language.<br/> <a href="http://www.w3.org/International/questions/qa-no-language">http://www.w3.org/International/questions/qa-no-language</a></li></ul><h4><a id="Td4e2687" name="Td4e2687">Test data</a></h4><ul><li>I18N Tests: Automatic font assignment for CJK text (for XHTML).<br/> <a href="http://www.w3.org/International/tests/sec-cjk-fonts.html">http://www.w3.org/International/tests/sec-cjk-fonts.html</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2687" name="Rd4e2687">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthDir" name="AuthDir" href="#AuthDir">Best Practice 17: Specifying text directionality</a></div><div class="rule">Use dedicated markup to specify the directionality of your text content.</div><div class="description"><p>Your schema should provide <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> (or an equivalent mechanism) to manage directionality. See <a class="technique-ref" href="#DevDir">Best Practice 2: Defining markup to specify text direction</a>.</p><p><strong>How to do this</strong></p><p>By default the text directionality in an XML document is assumed to be left-to-right. Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> (or its equivalent in your schema) on the root element of any document where the text runs predominantly from right-to-left, and on elements where the Unicode bidirectional algorithm needs help to achieve proper display of bidirectional text.</p><p>You can get additional guidance on when and how to use directional markup in  <a href="http://www.w3.org/TR/i18n-html-tech-bidi/">Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content</a> and <a href="/International/articles/inline-bidi-markup/">What you need to know about the bidi algorithm and inline markup</a>.  Although the first of these references is aimed at (X)HTML authors, the advice is generally relevant for authors of most XML-based documents too.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authdir-1" id="EX-authdir-1"></a>Example 20: Declaring text directionality</div><p>In this example, the attribute <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir">its:dir</a></code> is used to specify the directionality of a right-to-left text run in a document that is by default left-to-right.</p><pre>
<span class="element">&lt;text
  xmlns:its="http://www.w3.org/2005/11/its"  <span class="attribute">xml:lang</span>="en"
  <span class="attribute">its:version</span>="1.0"&gt;</span>
 <span class="element">&lt;body&gt;</span>
  <span class="element">&lt;par&gt;</span>In Hebrew, the title
     <span class="element">&lt;quote <span class="attribute">xml:lang</span>="he"
     <span class="attribute">its:dir</span>="rtl"&gt;</span><span dir="rtl">פעילות הבינאום, W3C</span><span class="element">&lt;/quote</span>&gt;
     means <span class="element">&lt;quote&gt;</span>Internationalization Activity, W3C<span class="element">&lt;/quote</span>&gt;.<span class="element">&lt;/par</span>&gt;
 <span class="element">&lt;/body</span>&gt;
<span class="element">&lt;/text</span>&gt;</pre><p>[<a href="EX-authdir-1.xml">Example's source code</a>]</p><p>Without the markup, the Hebrew title will  display incorrectly. The text 'W3C' and the comma will be to the right of the quoted Hebrew text, rather than to its left. The markup provides the contextual information that tells the user agent that  the comma and 'W3C' text are part of a right-to-left flow of text.</p><div class="note"><p><span class="note-head">Note: </span>This example shows the directionality of the source text correctly. This is to ensure that you understand the concepts being described. For such display, you need a sophisticated editor that resolves directionality of the source text correctly. Many editors are not yet this sophisticated. See the related discussion about <a href="http://www.w3.org/TR/i18n-html-tech-bidi/#d2e283">Problems with bidirectional source text</a> in <a title="Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content" href="#bidixhtmlbp">[Bidi in X/HTML]</a>.</p></div></div><div class="note"><p><span class="note-head">Note: </span>In XML documents, using markup is more appropriate than using <a href="http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/#Bidi">Unicode Bidi Embedding Controls</a>. See <a href="/International/questions/qa-bidi-controls">Bidi formatting codes vs. markup for bidi support</a> for a more detailed explanation.</p><p>You also need to use dedicated markup to apply directional information, rather than just applying CSS direction properties to ordinary elements.  See <a href="/International/questions/qa-bidi-css-markup">CSS vs. markup for bidi support</a> for further information.</p></div><p><strong>Why do this</strong></p><p>User agents should use the Unicode Bidirectional (bidi) Algorithm and its knowledge of  the directional properties of characters to decide whether a sequence of characters should flow to the left or to the right. The bidi algorithm can also handle simple cases where right-to-left and left-to-right text are mixed. However, situations commonly arise where higher level contextual information is needed to achieve the desired layout of bidirectional text. This contextual information can be provided by markup in XML. Such markup  also affects page layout behavior.  For example, in a right-to-left context, table columns are ordered right-to-left, list bullets appear to the right of text, the page is right-aligned, and so forth.</p><div class="note"><p><span class="note-head">Note: </span>Directionality information cannot be deduced from language markup:</p><ul><li><p>There is not necessarily a one-to-one match between a given language and what directionality to use. For example, Azerbaijani can be written using both right-to-left and left-to-right scripts, and the language code <code>az</code> is relevant for either.</p></li><li><p>The values of inline directional markup are not necessarily aligned with the values of markup about the language. For example, a part of a document might be declared as having right-to-left directionality, but there might be only a general language declaration for a left-to-right script language available, like <code>fr</code>.</p></li><li><p>Markup used to indicate directionality has values that indicate that the normal directionality should be overridden; it is not possible to indicate that using language related values.</p></li></ul></div></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e2817" name="BId4e2817">Background information</a></h4><ul><li>Internationalization FAQ: What you need to know about the bidi algorithm and inline markup<br/> <a href="http://www.w3.org/International/articles/inline-bidi-markup/">http://www.w3.org/International/articles/inline-bidi-markup/</a></li><li>Unicode Technical Report #20: Unicode in XML and other Markup Languages<br/> <a href="http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/">http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/</a></li></ul><h4><a id="RLd4e2817" name="RLd4e2817">Reference links</a></h4><ul><li>The "Directionality" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#directionality">http://www.w3.org/TR/2007/REC-its-20070403/#directionality</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e2817" name="Rd4e2817">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthTransOver" name="AuthTransOver" href="#AuthTransOver">Best Practice 18: Overriding information about what should be translated</a></div><div class="rule">Use available markup to specify any content where the choice to translate or not is different
		from the default for your schema.</div><div class="description"><p>Your schema should provide <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> (or an equivalent mechanism) to allow you to override defaults. See <a class="technique-ref" href="#DevTransOver">Best Practice 5: Defining markup to override translate information</a>.</p><p>The ITS default is that element content should be translated and attribute content should not. Developers of your schema should also have <a href="#DevITSRules">documented any schema-specific defaults</a> for your document type where these differ from the ITS default.</p><p><strong>How to do this</strong></p><p>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> (or its equivalent in your schema) on each element for which the translatability property is different from the defaults set for your schema.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authtransover-1" id="EX-authtransover-1"></a>Example 21: Overriding default translation rules</div><p>In the following document, although the content of the <code>par</code> elements should normally be translated, in this instance the last <code>par</code> should remain in English. Using <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> the author can indicate that the last <code>par</code> should not be translated.</p><p>Note that the author does not need to specify that the <code>head</code> element should not be translated, because this is  defined for all documents of type <code>myDoc</code> by the <a href="#DevITSRules">ITS Rules document</a>  provided by the developer of the <code>myDoc</code> schema (see just below).</p><pre>&lt;myDoc xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
&lt;head&gt;
  &lt;lastRev&gt;2007-10-23 041254Z&lt;/lastRev&gt;
  &lt;docID&gt;1A454AE4-7EB8-4ed2-A58E-1EC7F75BB0D5&lt;/docID&gt;
 &lt;/head&gt;
 &lt;par&gt;To apply these terms to you library, attach the following notice.
  It is safest to attach it to the start of each source file to most 
  effectively convey the exclusion of warranty; and each file should 
  have at least the "copyright" line and a pointer to where the full 
  notice is found.&lt;/par&gt;
  &lt;par&gt;The notice should read (preferably in English):&lt;/par&gt;
  &lt;par its:translate="no"&gt;This library is free software; you can 
  redistribute it and/or modify it under the terms of the GNU Lesser 
  General Public License as published by the Free Software Foundation; 
  either version 2.1 of the License, or (at your option) any later 
  version. This software is distributed as open source under LGPL.&lt;/par&gt;
 &lt;/myDoc&gt;</pre><p>[<a href="EX-devtransover-1.xml">Example's source code</a>]</p><p>This is the ITS Rules document  created by the developer of the <code>myDoc</code> document type (implementing <a class="technique-ref" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a>). These rules override the ITS default that all element content should be translated, but attribute values should not.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:translateRule selector="/myDoc/head" translate="no"/&gt;
 &lt;its:translateRule selector="//img/@alt" translate="yes"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-devtransover-4.xml">Example's source code</a>]</p><p>This is what the rules mean:</p><ul><li><p>First <code>translateRule</code>: The <code>head</code> element and its children should not be translated.</p></li><li><p>Second <code>translateRule</code>: The <code>alt</code> attribute of any <code>img</code> element should be translated.</p></li></ul></div><p>To override translate information for attributes, you have to use an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element in your document.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authtransover-2" id="EX-authtransover-2"></a>Example 22: Overriding default translation rules for attributes</div><p>This document is of the same type as the one in <a class="example-ref" href="#EX-authtransover-1">Example 21</a> and uses the same ITS rules, therefore the <code>alt</code> attribute should normally be translated. Because in this specific document the images refer to a user interface that will not be translated (whereas the document will be), the author needs to override the rule that all <code>alt</code> attributes should be translated. This is done at the top of the document, using  <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code>.</p><pre>&lt;myDoc xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
 &lt;head&gt;
  &lt;lastRev&gt;2007-11-12 234503Z&lt;/lastRev&gt;
  &lt;docID&gt;D1EA7453-DC53-488a-B950-137BE0EF5253&lt;/docID&gt;
  &lt;its:rules&gt;
   &lt;its:translateRule selector="//img[@role='ui']/@alt" translate="no"/&gt;
  &lt;/its:rules&gt;
 &lt;/head&gt;
 &lt;par&gt;Once you have selected your options, click the 
  &lt;img xml:lang="en-us" src="runBtn.png" role="ui" alt="Run"/&gt; button
  to start the process.&lt;/par&gt;
&lt;/myDoc&gt;</pre><p>[<a href="EX-authtransover-2.xml">Example's source code</a>]</p><p>The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element says that the alt text of images referring to UI buttons in the document should be left untranslated.</p></div><div class="note"><p><span class="note-head">Note: </span>Authors should NOT use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> to tag single words or terms that (they think) are likely to  remain the same when translated into a given target language (e.g. loan-words). This type of decision is normally made during translation.</p><p>Authors may decide <em>what</em> is translatable, but not <em>how</em> to translate it.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authtransover-3.xml" id="EX-authtransover-3.xml"></a>Example 23: XML document with inappropriate usage of <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code>.</div><p>This is an example of bad design. In this document <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> is used to markup a proper name and two loan words in an attempt to indicate that they should not be translated. You should <strong>not</strong> do this.</p><pre>&lt;book xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
 &lt;body&gt;
  &lt;p&gt;Everything started when &lt;span its:translate="no"&gt;Zebulon&lt;/span&gt; 
  discovered that he had a &lt;span its:translate="no"&gt;doppelgänger&lt;/span&gt; 
  who was a serious baseball &lt;span its:translate="no"&gt;aficionado&lt;/span&gt;.&lt;/p&gt;
 &lt;/body&gt;
&lt;/book&gt;</pre><p>[<a href="EX-authtransover-3.xml">Example's source code</a>]</p><p>It may, however,  be useful to the translator  to mark up loan-words or any special words in this example as <em>terms</em>, as described in the section  <a class="technique-ref" href="#AuthTermOver">Best Practice 23: Identifying terms</a>.</p></div></div><p><strong>Why do this</strong></p><p>Although the set of ITS rules provided with the schema should specify any exceptions to the default ITS translation rules for a given schema (see <a class="technique-ref" href="#DevTrans">Best Practice 4: Indicating which elements and attributes should be translated</a>), there are cases where these general rules need to be overridden for specific elements, in specific documents. It is up to the author of the content to indicate these cases using markup.</p></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthUniqueID" name="AuthUniqueID" href="#AuthUniqueID">Best Practice 19: Assigning unique identifiers</a></div><div class="rule">Assign a unique identifier to elements  that correspond to  segmentation boundaries.</div><div class="description"><p>Your schema should provide <code><a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">xml:id</a></code> (or an equivalent mechanism) to allow you to assign unique identifiers to elements. See <a class="technique-ref" href="#DevUniqueID">Best Practice 9: Defining markup for  unique identifiers</a>.</p><p>Segmentation refers to how text is broken down, from a linguistic viewpoint, into units that can be stored separately and handled by processes such as translation. The schema author ought to create a list of these elements  where they differ from the ITS defaults (see <a class="technique-ref" href="#DevSeg">Best Practice 6: Providing 
		information related to text segmentation</a>).</p><p><strong>How to do this</strong></p><p>Use unique identifiers in the way provided by your schema on each element that constitutes a segmentation boundary.</p><div class="note"><p><span class="note-head">Note: </span>Often, ids are automatically assigned by authoring or content management applications. Thus, authors may not have to worry about them 
in some cases.</p></div><p>If possible use <em>globally unique</em> and <em>persistent</em> values as identifier values.</p><p><strong>Why do this</strong></p><p>Providing unique identifiers can be very useful for change analysis, text tracking, and various other tasks often utilized during the authoring and the localization of documents.</p><p>This is explained in more detail in <a class="technique-ref" href="#DevUniqueID">Best Practice 9: Defining markup for  unique identifiers</a>.</p></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e3068" name="BId4e3068">Background information</a></h4><ul><li>"Give unique identifiers to elements in XML documents", note.<br/> <a href="http://www.ibm.com/developerworks/xml/standards/x-xmlidspec.html">http://www.ibm.com/developerworks/xml/standards/x-xmlidspec.html</a></li></ul><h4><a id="RLd4e3068" name="RLd4e3068">Reference links</a></h4><ul><li>W3C Recommendation: xml:id<br/> <a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">http://www.w3.org/TR/2005/REC-xml-id-20050909/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e3068" name="Rd4e3068">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthCDATA" name="AuthCDATA" href="#AuthCDATA">Best Practice 20: Avoiding CDATA sections</a></div><div class="rule">Avoid using CDATA sections for  content that will be translated.</div><div class="description"><p>CDATA sections are often used to place programming code or other special 
vocabularies in XML with minimal effort. There are often better ways of including such content.</p><p><strong>How to do this</strong></p><p>Do not put content that will be translated into CDATA sections.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authcdata-1" id="EX-authcdata-1"></a>Example 24: Avoiding the use of CDATA sections</div><p>This is an example of bad design. In this document, part of the content is in a CDATA section. It is no longer possible to mark up that content for language changes, terms, text direction, translate information, or any of the other things that may be needed to facilitate localization. </p><pre>&lt;myData&gt;
 &lt;item course="12" page="2"&gt;
  &lt;title&gt;Accessing the R&amp;amp;D facilities&lt;/title&gt;
  &lt;body&gt;&lt;![CDATA[The R&amp;D facilities are located in the South wing
   of Building 12-W, in the East quarter of the section Q.
   IMPORTANT ==&gt; These facilities are accessible only to personal with
   Class Omega-45Q1 clearance.]]&gt;&lt;/body&gt;
 &lt;/item&gt;
&lt;/myData&gt;</pre><p>[<a href="EX-authcdata-1.xml">Example's source code</a>]</p><p>Instead, use normal XML for your content. This allows you to tag the content as needed. For instance, here the author has added some terminology markup.</p><pre>&lt;myData xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
 &lt;item course="12" page="2"&gt;
  &lt;title&gt;Accessing the R&amp;amp;D facilities&lt;/title&gt;
  &lt;body&gt;The R&amp;amp;D facilities are located in the South wing
   of Building 12-W, in the East quarter of the section Q.
   IMPORTANT ==&amp;gt; These facilities are accessible only to personal with
   &lt;span its:term="yes"&gt;Class Omega-45-Q1&lt;/span&gt; clearance.&lt;/body&gt;
 &lt;/item&gt;
&lt;/myData&gt;</pre><p>[<a href="EX-authcdata-2.xml">Example's source code</a>]</p></div><p>If the CDATA section encloses a large, self-contained block of data, such as a script or an XML example, you may be able to replace the section by some inclusion mechanism such as <a href="#xinclude">XInclude</a> or <a href="#xlink1">XLink</a>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authcdata-3" id="EX-authcdata-3"></a>Example 25: Replacing CDATA sections with XLink</div><p>In SVG you can place a script directly into an SVG document, in which case you usually use CDATA sections to avoid having to escape characters in the script's code.</p><pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;svg width="6cm" height="5cm" viewBox="0 0 600 500"
     xmlns="http://www.w3.org/2000/svg" version="1.1"&gt;
  &lt;!-- Script is inlined and enclosed in CDATA section  --&gt;
  &lt;script type="text/ecmascript"&gt; &lt;![CDATA[
    function circle_click(evt) {
      var circle = evt.target;
      var currentRadius = circle.getAttribute("r");
      if (currentRadius &lt; 100)
        circle.setAttribute("r", currentRadius*2);
      else
        circle.setAttribute("r", currentRadius*0.5);
    }
  ]]&gt; &lt;/script&gt;
  &lt;rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/&gt;
  &lt;circle onclick="circle_click(evt)" cx="300" cy="225" r="10"
          fill="red"/&gt;
  &lt;text x="300" y="480" 
        font-family="Verdana" font-size="35" text-anchor="middle"&gt;
    Click on circle to change its size
  &lt;/text&gt;
&lt;/svg&gt;</pre><p>[<a href="EX-authcdata-3a.xml">Example's source code</a>]</p><p>Instead, you could use XLink to store the script in a separate file and reference it from the SVG document.</p><pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;svg width="6cm" height="5cm" viewBox="0 0 600 500"
     xmlns="http://www.w3.org/2000/svg" version="1.1"
     xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
  &lt;!-- Script is included from external file  --&gt;
  &lt;script type="text/ecmascript" xlink:href="animate.js"/&gt;
  &lt;rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/&gt;
  &lt;circle onclick="circle_click(evt)" cx="300" cy="225" r="10"
          fill="red"/&gt;
  &lt;text x="300" y="480" 
        font-family="Verdana" font-size="35" text-anchor="middle"&gt;
    Click on circle to change its size
  &lt;/text&gt;
&lt;/svg&gt;</pre><p>[<a href="EX-authcdata-3b.xml">Example's source code</a>]</p></div><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authcdata-4" id="EX-authcdata-4"></a>Example 26: Replacing CDATA sections with XInclude</div><p>It is quite common to use CDATA sections to put examples of source code into XML documents. The following example shows how to do this using DocBook.</p><pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;example xmlns="http://docbook.org/ns/docbook"&gt;
  &lt;title&gt;Skeleton of XHTML page&lt;/title&gt;
  &lt;programlisting&gt;&lt;![CDATA[&lt;html xmlns="http://www.w3.org/1999/xhtml"
   xml:lang="en"&gt;
  &lt;head&gt;
    &lt;title&gt;… page title goes here …&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
    … page content goes here …
  &lt;/body&gt;
&lt;/html&gt;]]&gt;&lt;/programlisting&gt;
&lt;/example&gt;
</pre><p>[<a href="EX-authcdata-4a.xml">Example's source code</a>]</p><p>Instead, you could use XInclude to store the example code in a separate file and include it during at processing time. Note that you have to use <code>parse="text"</code> to treat the included file as plain text rather than markup.</p><pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;example xmlns="http://docbook.org/ns/docbook"
	 xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
  &lt;title&gt;Skeleton of XHTML page&lt;/title&gt;
  &lt;programlisting&gt;&lt;xi:include href="EX-xhtml-skeleton.xhtml" 
			      parse="text"
			      encoding="utf-8"/&gt;&lt;/programlisting&gt;
&lt;/example&gt;
</pre><p>[<a href="EX-authcdata-4b.xml">Example's source code</a>]</p></div><p>If you must use CDATA sections:</p><ul><li><p>Document the type of content (for example with an attribute set to the appropriate MIME-type). This may help tools to use an appropriate parser to process the content.</p></li><li><p>Aim to produce well-formed content. This will allow parsers to process the content more easily.</p></li></ul><div class="note"><p><span class="note-head">Note: </span>CDATA is often used to store textual content containing HTML or XML tags. This is not recommended. See <a class="technique-ref" href="#AuthMarkupAsText">Best Practice 24: Storing markup from another format</a> for more details.</p></div><div class="note"><p><span class="note-head">Note: </span>Using CDATA does not affect whether white-space is preserved or not by XML processors. To preserve white-space use the <code><a href="http://www.w3.org/TR/REC-xml/#sec-white-space">xml:space</a></code> attribute with the value <code>preserve</code>.</p></div><p><strong>Why do this</strong></p><p>The use of CDATA sections prevents the insertion of markup for internationalization or localization purposes. For example, tags to denote change of directionality, or language, or to add localization notes, cannot be used with the content inside CDATA sections.</p><p>Numeric character references and entity references are not supported in CDATA sections either.  This could lead to a possible loss of data if the document is converted from one encoding to another, or when translating.</p><p>Mixing content in CDATA sections and content not in CDATA sections in the same document causes more work when doing some tasks with non-XML-aware tools. For example, when searching for the text "R&amp;D" the user has to search both for <code>R&amp;D</code> (for the CDATA sections) and <code>R&amp;amp;D</code> (for the normal content).</p></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthLocNote" name="AuthLocNote" href="#AuthLocNote">Best Practice 21: Providing notes for localizers</a></div><div class="rule">Use dedicated markup to provide notes where you can communicate useful information for the localizer</div><div class="description"><p>Your schema should provide <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code>, and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> (or equivalent mechanisms) to allow you to communicate with those who will localize your content. See <a class="technique-ref" href="#DevLocNote">Best Practice 8: Defining markup for  notes to localizers</a>.</p><p><strong>How to do this</strong></p><p>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> (or their equivalents in your schema) to provide notes to the localizer.</p><p>This is especially important for content with <a href="#AuthInsText">inserted text</a> where the translator will need context to translate more accurately.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authlocnote-1" id="EX-authlocnote-1"></a>Example 27: Annotating an XML document for localization</div><p>In this document two ITS local attributes are used to annotate an XSLT template:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code> is used to point to an explanation of the acronym RFID.</p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> is used to indicate what kind of value the element <code>&lt;xsl:value-of select="PNum"/&gt;</code> corresponds to.</p></li></ul><div class="note"><p><span class="note-head">Note: </span>When working with XSLT, you need to decide whether the ITS markup should be in the output or not, and may have to use different markup accordingly. In this example, the ITS attributes do not appear in the output.</p></div><pre>&lt;?xml version="1.0"?&gt;
&lt;xsl:stylesheet version="1.0"
     xmlns="http://www.w3.org/1999/xhtml"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:its="http://www.w3.org/2005/11/its"
     its:version="1.0"&gt;
 &lt;xsl:template match="/data"&gt;
  &lt;xsl:variable name="Lang" select="Lang"/&gt;
  &lt;xsl:variable name="EMail" select="EMail"/&gt;
  &lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{$Lang}" lang="{$Lang}"&gt;
   &lt;head&gt;
    &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8"/&gt;
    &lt;title&gt;Login&lt;/title&gt;
   &lt;/head&gt;
   &lt;body&gt;
    &lt;p&gt;Login Into Queztal-Systems&lt;/p&gt;
    &lt;form method="POST"&gt;
     &lt;table border="0" id="table2"&gt;
      &lt;tr&gt;&lt;td&gt;First, place your pass card in front of the reader to scan your
       &lt;xsl:text its:locNoteRef="http://en.wikipedia.org/wiki/RFID"&gt;RFID&lt;/xsl:text&gt;.
       When the light turns green, enter your password in the box below, and
       click Submit.&lt;/td&gt;&lt;/tr&gt;
      &lt;tr&gt;&lt;td&gt;&lt;input type="password" name="pword" size="25"/&gt;&lt;/td&gt;&lt;/tr&gt;
     &lt;/table&gt;
     &lt;p&gt;&lt;input type="submit" value="Submit" name="go"/&gt;&lt;/p&gt;
    &lt;/form&gt;
    &lt;p&gt;If you have difficulties login in, please call
     &lt;xsl:value-of select="PNum" its:locNote="Toll-free phone number"/&gt;,
     or send an email to
     &lt;a href="mailto:{$EMail}"&gt;&lt;xsl:value-of select="EMail"/&gt;&lt;/a&gt;.&lt;/p&gt;
   &lt;/body&gt;
  &lt;/html&gt;
 &lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</pre><p>[<a href="EX-authlocnote-1.xsl">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>There are many reasons to provide information to localizers. You may want to:</p><ul><li><p>Expand on the meaning or contextual usage of a particular element, such as what a variable refers to or how a string will be used in the user interface.</p></li><li><p>Clarify ambiguity and show relationships between items sufficiently to allow correct translation. For example, in many languages it is impossible to translate the word "enabled" in isolation without knowing the gender, number and case of the thing it refers to.</p></li><li><p>Explain why text is not translated, point to text reuse, or describe the use of conditional text.</p></li><li><p>Indicate why a piece of text is emphasized (important, sarcastic, etc.)</p></li></ul><p>Using XML comments for doing this may not be enough as they may get stripped out or ignored during the localization process.</p></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthInsText" name="AuthInsText" href="#AuthInsText">Best Practice 22: Working with inserted text</a></div><div class="rule">Make sure that any piece of inserted text is grammatically independent of its surrounding context.</div><div class="description"><p>Inserted text refers to any text that is marked by a placeholder in the source XML document and automatically inserted within text content when the document is processed.</p><p>Types of inserted text include:</p><ul><li><p>Boilerplate text reused in different contexts.</p></li><li><p>Various parts of a sentence composed by bringing together separate pieces of text.</p></li><li><p>Variable placeholders that are replaced by their values when the document is processed.</p></li></ul><p>The implementation of such text can be done in different ways in XML. Some examples are:</p><ul><li><p>Using entity references.</p></li><li><p>Using XSLT processing.</p></li><li><p>Using <a href="#xinclude">XInclude</a> mechanisms.</p></li><li><p>Using <a href="#xlink1">XLink</a> mechanisms.</p></li><li><p>Using a custom mechanism specific to a given format (e.g. the <code>conref</code> attribute in <a title="OASIS Darwin Information Typing&#xA;Architecture (DITA) Language Specification v1.0" href="#dita10">[DITA 1.0]</a>).</p></li></ul><p><strong>How to do this</strong></p><p>Use inserted text only when the text is self-contained and does not affect its surrounding context. For example, titles and quotations are inserted text that, usually, would not cause problems.</p><p>Avoid using inserted text that has any effect or dependence on the context where it is inserted.</p><p>For additional background information about issues and approaches related to text insertion and re-use of text see the articles <a href="http://www.w3.org/International/articles/composite-messages/">Working with Composite Messages</a> and <a href="http://www.w3.org/International/articles/text-reuse/">Re-using Strings in Scripted Content</a>.</p><p>If you do insert text, use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> or <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> (or their equivalents in your schema) to provide the localizers with some context. See <a class="technique-ref" href="#AuthLocNote">Best Practice 21: Providing notes for localizers</a> and <a class="technique-ref" href="#AuthTermOver">Best Practice 23: Identifying terms</a>.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authinstext-1" id="EX-authinstext-1"></a>Example 28: Providing context to variables.</div><p>In this example, in the first message, the element <code>var</code> is used to insert the name of a printer. In the second example, it is used to insert a filename. The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute is utilized to provide a description of what the variables represent. This may help in deciding how to translate each message.</p><pre>&lt;strings xmlns:its="http://www.w3.org/2005/11/its"
 xml:lang="en" its:version="1.0"&gt;
 &lt;msg id="pmAdded"&gt;The printer &lt;var arg="0" its:locNote="Printer name"/&gt; 
  has been added to the list.&lt;/msg&gt;
 &lt;msg id="fmAdded"&gt;The file &lt;var arg="0" its:locNote="Filename"/&gt; 
  has been added to the list.&lt;/msg&gt;
 &lt;/strings&gt;</pre><p>[<a href="EX-authinstext-1.xml">Example's source code</a>]</p><p>This is a French translation of the document shown above. The context provided allowed to disambiguate the variable and to get a more accurate translation.</p><pre>&lt;strings xmlns:its="http://www.w3.org/2005/11/its"
 xml:lang="fr" its:version="1.0"&gt;
 &lt;msg id="pmAdded"&gt;L'imprimante &lt;var arg="0" its:locNote="Printer name"/&gt; 
  a été ajoutée à la liste.&lt;/msg&gt;
 &lt;msg id="fmAdded"&gt;&lt;var arg="0" its:locNote="Filename"/&gt; 
  a été ajouté à la liste.&lt;/msg&gt;
&lt;/strings&gt;</pre><p>[<a href="EX-authinstext-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>If not used properly, inserted text can cause important (and sometimes unresolvable) problems during localization. Consider the following:</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e3411" id="d4e3411"></a>Example 29: Using <code>conref</code> in DITA</div><p>This is an example of bad design. In this example, the author, working with the DITA format <a title="OASIS Darwin Information Typing&#xA;Architecture (DITA) Language Specification v1.0" href="#dita10">[DITA 1.0]</a>, decided to reference a term in a termbase by using the <code>conref</code> mechanism. In this case, the term <code>t123</code> in <code>termbase.xml</code> has the value '<span class="qterm">hydraulic lift</span>'.</p><div class="exampleInner"><pre>&lt;p&gt;Using a &lt;term conref="termbase.xml#t123"/&gt;, raise the vehicle from the ground.&lt;/p&gt;</pre></div></div><p>At a first glance the example above seems to work fine in English. However, such a construction has several problems:</p><ul><li><p>You should not separate the article from the noun. If "hydraulic lift" is independently replaced in the future by some other term, you may need to change the article to '<span class="qterm">an</span>' or remove it.</p></li><li><p>The article/noun separation also causes trouble for the translators. Without any easy way to see the actual term when translating the paragraph, they may not be able to decide the gender or number of the article.</p></li><li><p>If it is used at the beginning of a different sentence, the term would need to be capitalized.</p></li><li><p>The term is singular in the termbase, but it may need to be plural somewhere else in the document.</p></li><li><p>In inflected languages the form required in the text may be different from the form stored in the termbase. For example, in Polish the term would be stored in its nominative form (<span xml:lang="pl" lang="pl">"<span class="quote" xml:lang="pl" lang="pl">dźwignia hydrauliczna</span>"</span>), while it should be in its instrumental form once inserted in this context: "<span class="quote" xml:lang="pl" lang="pl">Używając dźwignię hydrauliczną podnieś pojazd z ziemi.</span>"</p></li></ul></div><div class="resources"><div class="small-head">Resources:</div><h4 class="resource-first"><a id="BId4e3462" name="BId4e3462">Background information</a></h4><ul><li>Internationalization article: Working with Composite Messages.<br/> <a href="http://www.w3.org/International/articles/composite-messages/">http://www.w3.org/International/articles/composite-messages/</a></li><li>Internationalization article: Re-using Strings in Scripted Content<br/> <a href="http://www.w3.org/International/articles/text-reuse/">http://www.w3.org/International/articles/text-reuse/</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e3462" name="Rd4e3462">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthTermOver" name="AuthTermOver" href="#AuthTermOver">Best Practice 23: Identifying terms</a></div><div class="rule">Use dedicated markup to identify any terminology-related content.</div><div class="description"><p>What constitutes a term depends on many factors specific to each organization and project. Terms may include for example names of features, programs, services, and so forth. They also may include words or expressions that are specific to the domain to which the content pertains, such as technical terms, or legal terms, and they may include terms that simply occur often and should be translated consistently.</p><p><strong>How to do this</strong></p><p>Use <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> (or their equivalent in your schema) to mark terms and supply term-related information.</p><p>Your schema should provide <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> (or equivalent mechanisms). See <a class="technique-ref" href="#DevTermOver">Best Practice 11: Defining markup for specifying or overriding terminology-related information</a>.</p><p>You should also override default terminology rules as needed.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authtermover-1" id="EX-authtermover-1"></a>Example 30: Identifying terminology-related content</div><p>In this document, terms are normally denoted with a <code>term</code> element. Following <a class="technique-ref" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a>, the developer of the schema has provided an ITS Rules document that defines such property for <code>term</code>.</p><p>However, in this specific document, the author wants to indicate the following:</p><ul><li><p>The content of any <code>ui</code> element should be seen as a term.</p></li><li><p>The text <code>Vector Files</code> in the title is a term.</p></li></ul><p>In the first case, the author uses a <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> element in the header of the document to indicate that any <code>ui</code> element in this document is a term. This is more efficient than adding an attribute for each instance of <code>ui</code> in the body of the document.</p><p>In the second case, because the schema does not allow the element <code>term</code> to be used in <code>title</code> (an oversight of the developer), the author uses a simple <code>span</code> element with <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code> to associate <code>Vector Files</code> with its corresponding term information.</p><pre>&lt;myManual xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
 &lt;head&gt;
  &lt;its:rules&gt;
   &lt;its:termRule selector="//ui" term="yes"/&gt;
  &lt;/its:rules&gt;
  &lt;title&gt;Generating &lt;span its:term="yes" its:termInfoRef="#vFile"&gt;Vector 
   Files&lt;/span&gt;&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;par&gt;Select the command &lt;ui&gt;Build Output Files&lt;/ui&gt; from the 
   &lt;ui&gt;Tasks&lt;/ui&gt; menu to generate the final &lt;term ref="vFile"&gt;vector
   files&lt;/term&gt;.&lt;/par&gt;
 &lt;/body&gt;
 &lt;extra&gt;
  &lt;terms&gt;
   &lt;termDef xml:id="vFile"&gt;A &lt;emph&gt;vector file&lt;/emph&gt; is a binary document
    that contains the complete set of vectors needed to draw the background 
    layer of a map.&lt;/termDef&gt;
  &lt;/terms&gt;
 &lt;/extra&gt;
&lt;/myManual&gt;</pre><p>[<a href="EX-authtermover-1.xml">Example's source code</a>]</p><p>This ITS Rules document is the one created by the developer of the <code>myManual</code> document type (in implementing <a class="technique-ref" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a>). It provides one <code>termRule</code> element indicating that any <code>term</code> element is a term and its associated information is located in the element that is identified with the value stored in the <code>ref</code> attribute of <code>term</code>.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;its:termRule selector="//term" term="yes" termInfoRef="id(@ref)"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-authtermover-2.xml">Example's source code</a>]</p></div><p><strong>Why do this</strong></p><p>If you do not indicate what words are terms of interest in the content, the translators will not know that these terms need to be translated consistently. Often, multiple translators are working on different files in a given project, and the way they choose to translate specific words can be inconsistent with the way that other translators have translated them. If important terms are marked in the content, they can extract these terms from the content before the content is translated, and pre-translate them in the form of a shared electronic dictionary. This ensures consistency of translation of important terms.</p><p>While markup denoting terms for a given schema level should be specified in a set of ITS rules provided with the schema (See <a class="technique-ref" href="#DevTerm">Best Practice 10: Identifying terminology-related elements</a>), there are cases where these general rules need to be overridden or complemented for specific elements, in specific documents. It is up to the author of the content to provide such overriding markup.</p></div><div class="resources"><div class="small-head">Resources:</div><h4><a id="RLd4e3614" name="RLd4e3614">Reference links</a></h4><ul><li>The "Terminology" data category in ITS.<br/> <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">http://www.w3.org/TR/2007/REC-its-20070403/#terminology</a></li></ul><div class="techIndexPtr"><h4><a id="Rd4e3614" name="Rd4e3614">More resources</a></h4> <a href="/International/technique-index">Technique index</a> - <a href="/International/resource-index">Topic index</a></div></div><div class="short-name"><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a id="AuthMarkupAsText" name="AuthMarkupAsText" href="#AuthMarkupAsText">Best Practice 24: Storing markup from another format</a></div><div class="rule">Avoid escaping markup to enable storage of markup from another format.</div><div class="description"><p><strong>How to do this</strong></p><p>If possible, use the <a href="#xmlns">XML namespace mechanism</a> to store different vocabularies inside a single XML document.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-authmarkupastext-1" id="EX-authmarkupastext-1"></a>Example 31: How to avoid including markup in escaped form</div><p>In this document, the elements <code>top</code> and <code>body</code> both contain HTML markup coded as text. There is no easy way to make the distinction between the HTML markup and the HTML text content.</p><pre>&lt;pages&gt;
 &lt;row&gt;
  &lt;key&gt;ENConvClasses&lt;/key&gt;
  &lt;top&gt;&amp;lt;span class="h1"&amp;gt;Elibur Library&amp;lt;/span&amp;gt; - Conversation Groups&lt;/top&gt;
  &lt;body&gt;&lt;![CDATA[&lt;p&gt;These small discussion groups meet &lt;b&gt;weekly&lt;/b&gt; and are for
people learning English. Each group is led by a volunteer who is a native speaker 
of American English. Groups converse about books, articles, and other materials.&lt;/p&gt;
&lt;p&gt;Space is limited. Ask for availability to &lt;a href="mailto:enconv@elibur-lib.com"&gt;
enconv@elibur-lib.com&lt;/a&gt;.&lt;/p&gt;]]&gt;&lt;/body&gt;
 &lt;/row&gt;
&lt;/pages&gt;</pre><p>[<a href="EX-authmarkupastext-1.xml">Example's source code</a>]</p><p>Instead, use the XML namespace mechanism. Here the content of <code>top</code> and <code>body</code> is now a mix of text and XHTML elements. This avoid any confusion between text and HTML tags.</p><pre>&lt;pages xmlns:h="http://www.w3.org/1999/xhtml"&gt;
 &lt;row&gt;
  &lt;key&gt;ENConvClasses&lt;/key&gt;
  &lt;top&gt;&lt;h:span class="h1"&gt;Elibur Library&lt;/h:span&gt; - Conversation Groups&lt;/top&gt;
  &lt;body&gt;&lt;h:p&gt;These small discussion groups meet &lt;h:b&gt;weekly&lt;/h:b&gt; and are for
people learning English. Each group is led by a volunteer who is a native
speaker of American English. Groups converse about books, articles, and 
other materials.&lt;/h:p&gt;
&lt;h:p&gt;Space is limited. Ask for availability to &lt;h:a 
href="mailto:enconv@elibur-lib.com"&gt;enconv@elibur-lib.com&lt;/h:a&gt;.&lt;/h:p&gt;&lt;/body&gt;
 &lt;/row&gt;
&lt;/pages&gt;</pre><p>[<a href="EX-authmarkupastext-2.xml">Example's source code</a>]</p></div><p>Another alternative to using markup as text is to store it externally and include it into the document using a mechanism such as <a href="#xinclude">XInclude</a> or <a href="#xlink1">XLink</a>.</p><p>If you must include markup as text content:</p><ul><li><p>Make sure to document the type of content, for example with an attribute set to the appropriate MIME-type. This may help tools to use a more appropriate parser to process the given content.</p></li><li><p>Aim at having the content well-formed. This will allow parsers to process it more easily.</p></li></ul><p><strong>Why do this</strong></p><p>Some XML documents are used to store different types of data for purposes such as exchange or export. In some cases such data is itself XML data. For example, some XHTML content stored in a database can be exported to an XML container file for localization and re-imported back into the database.</p><div class="note"><p><span class="note-head">Note: </span>The use of escaping for literal examples of markup is not a problem. The issue is only for large volume of XML/HTML data contained in another XML document.</p></div><p>Storing such XML data inside XML elements as text content (i.e. with its markup tags escaped), has several drawbacks:</p><ul><li><p>Any handling of such content is made difficult by the impossibility to separate text from markup without extra processing.</p></li><li><p>Often, such content is put in CDATA sections, which has its own set of issues. See <a class="technique-ref" href="#AuthCDATA">Best Practice 20: Avoiding CDATA sections</a>.</p></li><li><p>The escaped markup cannot be validated.</p></li><li><p>If there is a process turning markup into escaping, there is the danger of double escaping.</p></li></ul></div></div><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="Generic" id="Generic"></a>4 Generic Techniques</h2><p>This section provides a set of generic techniques that are applicable to various guidelines; for example, how to add ITS attributes to different types of schemas, or how to optimize XPath expressions for the ITS <code>selector</code> attribute.</p><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="GenericWritingITSRules" id="GenericWritingITSRules"></a>4.1 Writing ITS Rules</h3><p>Whether they are external or embedded, there are a few things you should take into consideration when writing ITS rules.</p><ul><li><p>Try to keep the number of nodes to be overridden to a minimum. This improves performance. For example, if most of a document should not be translated, it is better to set the root element to be non-translatable than to set all elements. The inheritance mechanism will have the same effect for a much lower computing cost.</p></li><li><p>Because a rule has precedence over the ones before, you should start with the most general rules first and progressively override them as needed. Some rules may be more complex if they need to take into account all the aspects of inheritance.</p></li></ul><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="GenPrecInherit" id="GenPrecInherit"></a>4.1.1 Precedence and Inheritance</h4><p>ITS 1.0 defines the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-precedence">precedence of ITS information</a> for  data categories. The precedence order for selection is as follows (starting with the highest precedence) and will be explained using the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>:</p><ol class="depth1"><li><p>ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-local">local attributes</a> on a specific element, for example the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute, have the highest precedence.</p></li><li><p>Next are <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-global">global rules</a>, for example a set of <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> elements for the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>. Individual rules in an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element have an inherent precedence which depends on their position in the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element: the rules at the bottom have a higher precedence than rules at the top. In addition, the rules inside a given <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element have a higher precedence than the rules linked via an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules.attributes">xlink:href</a></code> attribute in that same <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element.</p></li><li><p><a href="http://www.w3.org/TR/2007/REC-its-20070403/#datacategories-defaults-etc">Inherited ITS information</a> constitutes the third level of precedence. The kind of inheritance is data category specific. For example, if an element has been labelled as "do not translate" using one of the means described via 1) or 2) above, this information is inherited by its child elements, but not by attributes.</p></li><li><p>ITS information which originates in data category specific defaults is the one with the lowest precedence. For example, the default for the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a> is that element content is to be translated and attribute values are not to be translated.</p></li></ol><p>The following example shows the usage of local and global ITS markup and how the precedence described above comes into play.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-precedence-inheritance" id="EX-precedence-inheritance"></a>Example 32: Precedence and inheritance in ITS</div><p>In this document, all child elements within the <code>&lt;text&gt;</code> element are set as to 'do not translate' by the first <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element. However, the second and last <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element has higher precedence than the one before, so it can be used to describe an exception: all <code>&lt;p&gt;</code> elements are still to be translated. This shows the interplay between different rules and demonstrates that the last one always "wins".</p><p>Another exception to the first <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element is expressed with the local <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute on the <code>&lt;notes&gt;</code> element. It specifies that the content of this element should be translated. Without the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code> attribute, the information from the first <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element would be inherited, and this <code>&lt;notes&gt;</code> element would not be translatable.</p><p>Finally, the content of the <code>&lt;documentation&gt;</code> element within the <code>&lt;head&gt;</code> element is also translatable, but not the content of any attributes in the document. This demonstrates the role of defaults for the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat">ITS Translate data category</a>.</p><pre>&lt;doc xmlns:its="http://www.w3.org/2005/11/its"&gt;
 &lt;head&gt;
  &lt;documentation&gt;Some translatable text.&lt;/documentation&gt;
  &lt;its:rules version="1.0"&gt;
   &lt;its:translateRule selector="//text" translate="no"/&gt;
   &lt;its:translateRule selector="//p" translate="yes"/&gt;
  &lt;/its:rules&gt;
 &lt;/head&gt;
 &lt;text&gt;
  &lt;data&gt;Some data with &lt;code&gt;coded parts&lt;/code&gt; (&lt;notes 
its:translate="yes"&gt; and translatable text&lt;/notes&gt;).&lt;/data&gt;
  &lt;p&gt;Some text with &lt;b&gt;bolded words&lt;/b&gt;.&lt;/p&gt;
 &lt;/text&gt;
&lt;/doc&gt;</pre><p>[<a href="EX-precedence-inheritance.xml">Example's source code</a>]</p></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="GenNamespaces" id="GenNamespaces"></a>4.1.2 Dealing with namespaces</h4><p>When writing rules for documents that use XML namespaces you must make sure that you declare the namespaces, and use the relevant prefixes in the different XPath expressions.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e3865" id="d4e3865"></a>Example 33: Applying ITS rules on a document containing namespaces</div><p>The first document uses several different XML vocabularies:</p><ul><li><p>The host format is not associated with any namespace. Its elements have no prefix.</p></li><li><p>The "inventory-book" vocabulary is associated with the namespace <code>http://www.example.com/inventory-book</code>. The elements belonging to that namespace have a <code>bk</code> prefix.</p></li><li><p>The XHTML vocabulary is associated with the namespace <code>http://www.w3.org/1999/xhtml</code>. The elements belonging to that namespace ave a <code>h</code> prefix.</p></li><li><p>The XLink vocabulary is associated with the namespace <code>http://www.w3.org/1999/xlink</code>. There is one attribute belonging to that namespace and it has a <code>xlink</code> prefix.</p></li><li><p>The ITS vocabulary is associated with the namespace <code>http://www.w3.org/2005/11/its</code>. There is one element belonging to that namespace and it has an <code>its</code> prefix.</p></li></ul><pre>&lt;inventory xmlns:bk="http://www.example.com/inventory-book"
 xmlns:h="http://www.w3.org/1999/xhtml"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:its="http://www.w3.org/2005/11/its"&gt;
 &lt;header&gt;
  &lt;identity&gt;3E039D7D-B416-47e8-83B3-3F4DF9EDDB87&lt;/identity&gt;
  &lt;lastUpdate&gt;2007-11-12&lt;/lastUpdate&gt;
  &lt;desc&gt;Inventory made by Joan, for shelves H to K only.&lt;/desc&gt;
  &lt;its:rules version="1.0" xlink:href="EX-namespaces-2.xml" xlink:type="simple"/&gt;
 &lt;/header&gt;
 &lt;list&gt;
  &lt;bk:book xml:id="item00A83"&gt;
   &lt;bk:isbn&gt;0312875819&lt;/bk:isbn&gt;
   &lt;bk:quantity&gt;2&lt;/bk:quantity&gt;
   &lt;bk:type&gt;HIST&lt;/bk:type&gt;
   &lt;bk:author&gt;Bradshaw, Gillian&lt;/bk:author&gt;
   &lt;bk:pub&gt;Forge Books; New Ed edition (June 2, 2001)&lt;/bk:pub&gt;
   &lt;bk:title&gt;The Sand-Reckoner&lt;/bk:title&gt;
   &lt;bk:desc&gt;
    &lt;h:p&gt;Building on a few antique facts, Bradshaw ably recreates the extraordinary 
life of Archimedes, the great mathematician and engineer who lived in Syracuse from
287 to 212 B.C. After a few years studying in Alexandria, Archimedes returns home
where his father is dying and his city at war with the Romans.
&lt;h:img src="0312875819large.png" alt="The Sand-Reckoner (by Gillian Bradshaw)"/&gt;
&lt;/h:p&gt;
   &lt;/bk:desc&gt;
  &lt;/bk:book&gt;
 &lt;/list&gt;
&lt;/inventory&gt;</pre><p>[<a href="EX-namespaces-1.xml">Example's source code</a>]</p><p>The XLink and ITS namespaces are just used for associating this document with the external ITS rules file shown below.</p><p>The ITS Rules document contains several rules that determine what parts of the inventory document should be translated. The rules use XPath expressions where the elements are prefixed. These prefixes are associated with the namespaces used in the inventory. Here is a description of each <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code>, from top to bottom:</p><ul><li><p>The first indicates that the <code>inventory</code> element should not  be translated. This is inherited by all the children of <code>inventory</code>. Most of the content of the inventory is not to be translated, so the easiest way to define the proper rules for this type of document is to say that the root element should not be translated, and then list all the exceptions.</p></li><li><p>The second indicates that the <code>desc</code> element of the host format should be translated.</p></li><li><p>The third indicates that the <code>title</code> of the <code>http://www.example.com/inventory-book</code> namespace should be translated.</p></li><li><p>The fourth indicates that the <code>desc</code> element of the <code>http://www.example.com/inventory-book</code> namespace should be translated.</p></li><li><p>The last indicates that the <code>alt</code> attribute in the HTML <code>img</code> element should be translated.</p></li></ul><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"
 xmlns:book="http://www.example.com/inventory-book"
 xmlns:html="http://www.w3.org/1999/xhtml"&gt;
 &lt;its:translateRule selector="//inventory" translate="no"/&gt;
 &lt;its:translateRule selector="//desc" translate="yes"/&gt;
 &lt;its:translateRule selector="//book:title" translate="yes"/&gt;
 &lt;its:translateRule selector="//book:desc" translate="yes"/&gt;
 &lt;its:translateRule selector="//html:img/@alt" translate="yes"/&gt;
&lt;/its:rules&gt;
</pre><p>[<a href="EX-namespaces-2.xml">Example's source code</a>]</p></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="GenXPath" id="GenXPath"></a>4.1.3 Create your XPath expressions with care</h4><p>ITS uses XPath expressions in several contexts to identify nodes. The most prominent contexts are selectors, and pointer attributes like those shown in the following rules:</p><div class="exampleInner"><pre>&lt;its:translateRule selector="//term" translate="no"/&gt;</pre></div><p>or</p><div class="exampleInner"><pre>&lt;its:locNoteRule locNoteType="description" selector="//msg/data"
 locNotePointer="../notes"/&gt;</pre></div><p>When writing ITS-related XPath expressions like the ones above, the following should be considered:</p><ul><li><p>ITS XPath expressions pertain to XPath 1.0 or its successor</p></li><li><p>The values of ITS selector attributes are XPath absolute location paths</p></li><li><p>The values of ITS pointer attributes are XPath relative location paths. The ITS pointer attributes are: <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule.attributes">locNotePointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#locNoteRule.attributes">locNoteRefPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule.attributes">its:termInfoPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule.attributes">its:termInfoRefPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rubyPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rtPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rpPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rbcPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rtcPointer</a></code>, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rubyRule.attributes">its:rbspanPointer</a></code>, and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#langRule.attributes">its:langPointer</a></code>.</p></li></ul><p>In environments where XSLT is used to process ITS-related XPath expressions, it is important to know about the subset of XPath which is termed '<span class="qterm">XSLT patterns</span>' (see the note in the section <a href="http://www.w3.org/TR/2007/REC-its-20070403/#basic-concepts-selection-global">Global Approach</a> of the ITS Specification). Using only XSLT patterns in ITS selector attributes helps to avoid issues which may arise with respect to the <code>match</code> attribute in XSLT <code>template</code> elements.</p><p>In addition to this general advice, you should take into account best practices related to writing XPath expressions (see for example the <a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html">XPath tutorial</a>).</p></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="generic_insertatt" id="generic_insertatt"></a>4.2 Example of adding an attribute to an existing schema</h3><p>This example shows how to add an attribute (here <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code>) to an existing document type. We will add the attribute to an element called <code>para</code>.</p><p>Note that this example only shows a few ways of adding attributes. There are many others, depending on the schema language and the modularization techniques used in the existing schema.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="generic-includeinxsd" id="generic-includeinxsd"></a>4.2.1 Including <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in XML Schema</h4><p>To include the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute in your XML Schema document, import the W3C xml.xsd schema into your own schema using the <code>xs:import</code> element.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4090" id="d4e4090"></a>Example 34: Importing the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> declaration in XML Schema.</div><div class="exampleInner"><pre>&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"&gt;
 &lt;!-- Import for xml:lang and xml:space --&gt;
 &lt;xs:import namespace="http://www.w3.org/XML/1998/namespace"
            schemaLocation="http://www.w3.org/2001/xml.xsd"/&gt;
 ...</pre></div></div><p>Once the xml.xsd schema is imported, you can use the reference to <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in any of your element declarations.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4105" id="d4e4105"></a>Example 35: Using <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in XML Schema.</div><div class="exampleInner"><pre>... 
&lt;xs:element name="para"&gt;
 &lt;xs:complexType&gt;
  &lt;xs:sequence maxOccurs="unbounded"&gt;
    ...
  &lt;/xs:sequence&gt;
  &lt;xs:attribute ref="xml:lang" use="optional"/&gt;
 &lt;/xs:complexType&gt;
&lt;/xs:element&gt;
...</pre></div></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="generic-includeinrng" id="generic-includeinrng"></a>4.2.2 Including <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in RELAX NG</h4><p>Declare <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> directly in your schema. There is no existing declaration of, or standardized schema fragment defining, the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> attribute in RELAX NG. You have to declare
 <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> directly in your schema and specify the  choice of values to be either the XML Schema  <code>language</code> datatype  or an empty value.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4138" id="d4e4138"></a>Example 36: Declaration of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in RELAX NG.</div><div class="exampleInner"><pre>&lt;element name="para" 
         xmlns="http://relaxng.org/ns/structure/1.0" 
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"&gt;
  &lt;attribute name="xml:lang"&gt;
    &lt;choice&gt;
      &lt;data type="language"/&gt;
      &lt;value&gt;&lt;/value&gt;
    &lt;/choice&gt;
  &lt;/attribute&gt;
  ...
&lt;/element&gt;</pre></div></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="generic-includeindtd" id="generic-includeindtd"></a>4.2.3 Including <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in an XML DTD</h4><p>Add the <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> directly in the attribute list of your element.</p><p>For example, to add <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> to a <code>para</code> element you can specify the following in a DTD:</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4169" id="d4e4169"></a>Example 37: Declaration of <code><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">xml:lang</a></code> in a DTD.</div><div class="exampleInner"><pre>&lt;!ELEMENT para (#PCDATA)&gt; 
&lt;!ATTLIST para
          xml:lang CDATA #IMPLIED&gt;</pre></div></div></div></div></div><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="Modularization" id="Modularization"></a>5 ITS Applied to Existing Formats</h2><p>This section presents several examples of how ITS can be used to enhance the internationalization readiness of some well-known XML document types. These examples are only illustrative and may have to be adapted to fit the needs of each specific user.</p><p>Two topics are covered for each format:</p><ul><li><p>How should ITS be integrated in specific markup schemas? For example, for XHTML it promotes the  interoperability of ITS implementations if you specify that the ITS <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">rules</a></code> element will always be part of the content model of the <code>head</code> element.</p></li><li><p>How should ITS data categories be associated with existing markup declarations in a schema that have identical or overlapping purposes? For example, DITA <a title="OASIS Darwin Information Typing&#xA;Architecture (DITA) Language Specification v1.0" href="#dita10">[DITA 1.0]</a> already has an attribute to indicate translatability of text, but doesn't have a global <a href="http://www.w3.org/TR/2007/REC-its-20070403/#def-selection">selection</a> mechanism for indicating  what parts of an XML document the  ITS translate data category and its values should be applied to.</p></li></ul><p>The following XML vocabularies are discussed:</p><ul><li><p><a class="section-ref" href="#its-plus-xhtml10">Section 5.1: ITS and XHTML 1.0</a></p></li><li><p><a class="section-ref" href="#tei-modularization">Section 5.2: ITS and TEI</a></p></li><li><p><a class="section-ref" href="#xmlspec">Section 5.3: ITS and XML Spec</a></p></li><li><p><a class="section-ref" href="#dita">Section 5.4: ITS and DITA</a></p></li><li><p><a class="section-ref" href="#glade">Section 5.5: ITS and GladeXML</a></p></li><li><p><a class="section-ref" href="#docbook">Section 5.6: ITS and DocBook</a></p></li></ul><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="its-plus-xhtml10" id="its-plus-xhtml10"></a>5.1 ITS and XHTML 1.0</h3><p>XHTML <a title="XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition)" href="#xhtml10">[XHTML 1.0]</a> is a reformulation of the three HTML 4 document types as applications of XML 1.0. HTML is an SGML (Standard Generalized Markup Language) application, widely regarded as the standard publishing language of the World Wide Web.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="integration-its-xhtml" id="integration-its-xhtml"></a>5.1.1 Integrating  ITS into XHTML</h4><p>In XHTML 1.0, the XHTML namespace may be used with other XML namespaces as per <cite>Namespaces in XML</cite> <a title="Namespaces in XML" href="#xmlns">[XML Names]</a>, but such documents are <a href="http://www.w3.org/TR/2002/REC-xhtml1-20020801/#well-formed">no longer strictly conformant</a> XHTML 1.0.</p><p> Here is an example of a document containing ITS rules which is  a <em>non-conformant</em> XHTML 1.0 document.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4250" id="d4e4250"></a>Example 38: ITS rules in a non-conformant XHTML 1.0 document</div><pre>&lt;html xmlns="http://www.w3.org/1999/xhtml"
 xmlns:its="http://www.w3.org/2005/11/its" lang="en" xml:lang="en"&gt;
 &lt;head&gt;
  &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
  &lt;meta name="keywords" content="ITS example, XHTML translation" /&gt;
  &lt;its:rules version="1.0" xmlns:h="http://www.w3.org/1999/xhtml"&gt;
   &lt;its:translateRule selector="//h:meta[@name='keywords']/@content"
    translate="yes" /&gt;
   &lt;its:termRule selector="//h:span[@class='term']" term="yes" /&gt;
  &lt;/its:rules&gt;
  &lt;title&gt;ITS Working Group&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;h1&gt;Test of ITS on &lt;span class="term"&gt;XHTML&lt;/span&gt;&lt;/h1&gt;
  &lt;p&gt;Some text to translate.&lt;/p&gt;
  &lt;p its:translate="no"&gt;Some text not to translate.&lt;/p&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre><p>[<a href="EX-integration-its-xhtml-1.xml">Example's source code</a>]</p></div><p>There are three ways to use ITS with XHTML and keep the XHTML document conformant:</p><ol class="depth1"><li><p>Use XHTML Modularization <a title="XHTML™ Modularization 1.1" href="#xhtmlmod">[XHTMLMod1.1]</a>. See <a class="section-ref" href="#integration-its-xhtmlmod">Section 5.1.2: Using XHTML Modularization 1.1 for the Definition of ITS</a> for details.</p></li><li><p>Use external ITS global rules, as shown in the following example. Even local information within the document that would be handled by ITS attributes can be set indirectly.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4272" id="d4e4272"></a>Example 39: ITS external rules for XHTML</div><p>These rules illustrate some of the ITS data categories you can associate with specific XHTML markup. The first <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> indicates that the attribute <code>content</code> of the <code>meta</code> element should be translated if the attribute <code>name</code> is set to "keywords". The second <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> indicates that no <code>p</code> with a <code>class="notrans"</code> should be translated. And the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#termRule">its:termRule</a></code> indicates that any <code>span</code> element with <code>class="term"</code> is a term.</p><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"
 xmlns:h="http://www.w3.org/1999/xhtml"&gt;
 &lt;its:translateRule selector="//h:meta[@name='keywords']/@content"
  translate="yes" /&gt;
 &lt;its:translateRule selector="//h:p[@class='notrans']"
  translate="no" /&gt;
 &lt;its:termRule selector="//h:span[@class='term']" term="yes" /&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-integration-its-xhtml-2.xml">Example's source code</a>]</p><p>The corresponding document:</p><pre>&lt;html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"&gt;
 &lt;head&gt;
  &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
  &lt;meta name="keywords" content="ITS example, XHTML translation" /&gt;
  &lt;title&gt;ITS Working Group&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;h1&gt;Test of ITS on &lt;span class="term"&gt;XHTML&lt;/span&gt;&lt;/h1&gt;
  &lt;p&gt;Some text to translate.&lt;/p&gt;
  &lt;p class="notrans"&gt;Some text not to translate.&lt;/p&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre><p>[<a href="EX-integration-its-xhtml-3.xml">Example's source code</a>]</p></div></li><li><p>Use NVDL. See <a class="section-ref" href="#integration-its-xhtml-nvdl">Section 5.1.3: Using NVDL to integrate ITS into XHTML</a> for details.</p></li></ol></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="integration-its-xhtmlmod" id="integration-its-xhtmlmod"></a>5.1.2 Using XHTML Modularization 1.1 for the Definition of ITS</h4><p>This section describes how to use XHTML Modularization 1.1 <a title="XHTML™ Modularization 1.1" href="#xhtmlmod">[XHTMLMod1.1]</a> for the definition of ITS. It first defines an ITS abstract module which is then implemented in the XML Schema format. The module is meant to be integrated in existing or new schemas which rely on XHTML Modularization 1.1.</p><div class="div4">
<h5><a name="d4e4337" id="d4e4337"></a>5.1.2.1 Abstract Definition of ITS Markup</h5><p>The following is the abstract definition of the elements for <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-global">global ITS markup</a>, which is consistent with the XHTML Modularization framework <a title="XHTML™ Modularization 1.1" href="#xhtmlmod">[XHTMLMod1.1]</a>. Further definitions of XHTML abstract modules can be found in the XHTML Modularization specification <a title="XHTML™ Modularization 1.1" href="#xhtmlmod">[XHTMLMod1.1]</a>.</p><p>Note that this definition does not contain the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">ruby</a> element and the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.dir.attributes">dir</a> attribute, since these are already available in XHTML. Such existing markup should be associated with ITS data categories using an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element. See <a class="section-ref" href="#relating-its-plus-xhtml">Section 5.1.4: Associating existing XHTML markup with ITS</a>.</p><table border="1" width="100%"><thead><tr><th>Elements</th><th>Attributes</th><th>Minimal Content Model</th></tr></thead><tbody><tr><td id="el-rules">rules</td><td>version (CDATA), xlink:href (URI), xlink:type ("simple")</td><td> ( <a href="#el-translateRule">translateRule</a>  | <a href="#el-locNoteRule">locNoteRule</a>  
	| <a href="#el-termRule">termRule</a>  | <a href="#el-dirRule">dirRule</a>  | 
	<a href="#el-rubyRule">rubyRule</a>  | <a href="#el-langRule">langRule</a>  |
	 <a href="#el-withinTextRule">withinTextRule</a>  )*</td></tr><tr id="el-translateRule"><td>translateRule</td><td><a href="#att-selector">Selector</a>, translate ("yes"|"no")</td><td>EMPTY</td></tr><tr id="el-locNoteRule"><td>locNoteRule</td><td><a href="#att-selector">Selector</a>, locNotePointer (CDATA), locNoteType ("alert"| "description"), locNoteRef (URI), locNoteRefPointer (CDATA)</td><td><a href="#el-locNote">locNote?</a></td></tr><tr id="el-locNote"><td>locNote</td><td>translate ("yes"|"no"), locNote (CDATA), locNoteType ( "alert" | "description"), locNoteRef (URI), termInfoRef ( URI ), term ( "yes" | "no" ), dir ( "ltr" | "rtl" | "lro" | "rlo" )</td><td>(PCDATA | <a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">ruby</a>)*</td></tr><tr id="el-termRule"><td>termRule</td><td><a href="#att-selector">Selector</a>, term ( "yes" | "no" ), termInfoRef ( URI ), termInfoRefPointer ( CDATA), termInfoPointer ( CDATA )</td><td>EMPTY</td></tr><tr id="el-dirRule"><td>dirRule</td><td><a href="#att-selector">Selector</a>, dir ("ltr" | "rtl" | "lro" | "rlo")</td><td>EMPTY</td></tr><tr id="el-rubyRule"><td>rubyRule</td><td><a href="#att-selector">Selector</a>, rubyPointer (CDATA), rtPointer (CDATA), rpPointer (CDATA), rbcPointer (CDATA), rtcPointer (CDATA), rbspanPointer (CDATA)</td><td><a href="#el-rubyText">rubyText</a></td></tr><tr id="el-rubyText"><td>rubyText</td><td>translate ("yes"|"no"), locNote (CDATA), locNoteType ("alert"|"description"), locNoteRef (URI), term ("yes" | "no"), termInfoRef (CDATA), dir ("ltr" | "rtl" | "lro" | "rlo" ), rbspan (CDATA)</td><td>PCDATA</td></tr><tr id="el-langRule"><td>langRule</td><td><a href="#att-selector">Selector</a>, langPointer (CDATA)</td><td>EMPTY</td></tr><tr id="el-withinTextRule"><td>withinTextRule</td><td><a href="#att-selector">Selector</a>, withinText ("yes"|"no"|"nested")</td><td>EMPTY</td></tr></tbody></table><p>The following are the abstract definitions of two attribute groups: the <a href="#att-selector">selector</a> attribute used within <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-global">global rules</a>, and <a href="http://www.w3.org/TR/2007/REC-its-20070403/#selection-local">ITS attributes to be used locally</a>. Again these definitions make use of XHTML Modularization 1.1.</p><table border="1" width="100%"><thead><tr><th>Collection</th><th>Attributes in Collection</th></tr></thead><tbody><tr id="att-selector"><td>Selector</td><td>selector (CDATA)</td></tr><tr id="att-its-local"><td>ITSLocal</td><td>translate ("yes"|"no"), locNote (CDATA), locNoteType ("alert"|"description"), locNoteRef (URI), termInfoRef (URI), term ("yes" | "no")</td></tr></tbody></table></div><div class="div4">
<h5><a name="d4e4513" id="d4e4513"></a>5.1.2.2ITS XML Schema Module Implementation</h5><p>The following schema contains the implementation of the abstract markup module in XML Schema.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4518" id="d4e4518"></a>Example 40: </div><div class="exampleInner"><pre>&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.w3.org/2005/11/its"
    xmlns:its="http://www.w3.org/2005/11/its"
    xmlns:h="http://www.w3.org/1999/xhtml" elementFormDefault="qualified"
    xmlns:xlink="http://www.w3.org/1999/xlink"&gt;
    &lt;xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd"/&gt;
    &lt;xs:import namespace="http://www.w3.org/1999/xhtml"
        schemaLocation="xhtml-schemas/xhtml-ruby-1.xsd"/&gt;
    &lt;xs:simpleType name="translate.type"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="yes"/&gt;
            &lt;xs:enumeration value="no"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="term.type"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="yes"/&gt;
            &lt;xs:enumeration value="no"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="locNoteType.type"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="alert"/&gt;
            &lt;xs:enumeration value="description"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="dir.type"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="ltr"/&gt;
            &lt;xs:enumeration value="ltr"/&gt;
            &lt;xs:enumeration value="lro"/&gt;
            &lt;xs:enumeration value="rlo"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:simpleType name="withinText.type"&gt;
        &lt;xs:restriction base="xs:string"&gt;
            &lt;xs:enumeration value="yes"/&gt;
            &lt;xs:enumeration value="no"/&gt;
            &lt;xs:enumeration value="nested"/&gt;
        &lt;/xs:restriction&gt;
    &lt;/xs:simpleType&gt;
    &lt;xs:attributeGroup name="its.Selector.attlist"&gt;
        &lt;xs:attribute name="selector" type="xs:string" use="required"/&gt;
    &lt;/xs:attributeGroup&gt;
    &lt;xs:attributeGroup name="its.ITSLocal.attlist"&gt;
        &lt;xs:attribute name="translate" form="qualified" use="optional"
         type="its:translate.type"/&gt;
        &lt;xs:attribute name="locNote" type="xs:string" form="qualified" 
         use="optional"/&gt;
        &lt;xs:attribute name="locNoteType" form="qualified" use="optional"
         type="its:locNoteType.type"/&gt;
        &lt;xs:attribute name="locNoteRef" type="xs:anyURI" form="qualified"
         use="optional"/&gt;
        &lt;xs:attribute name="termInfoRef" type="xs:string" form="qualified"
         use="optional"/&gt;
        &lt;xs:attribute name="term" type="its:term.type" form="qualified"
         use="optional"/&gt;
    &lt;/xs:attributeGroup&gt;
    &lt;xs:element name="rules" type="its:rules.type"/&gt;
    &lt;xs:complexType name="rules.type" mixed="false"&gt;
        &lt;xs:choice minOccurs="0" maxOccurs="unbounded"&gt;
            &lt;xs:element ref="its:translateRule"/&gt;
            &lt;xs:element ref="its:locNoteRule"/&gt;
            &lt;xs:element ref="its:termRule"/&gt;
            &lt;xs:element ref="its:dirRule"/&gt;
            &lt;xs:element ref="its:rubyRule"/&gt;
            &lt;xs:element ref="its:langRule"/&gt;
            &lt;xs:element ref="its:withinTextRule"/&gt;
        &lt;/xs:choice&gt;
        &lt;xs:attributeGroup ref="its:rules.attlist"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:attributeGroup name="rules.attlist"&gt;
        &lt;xs:attribute name="version" use="required" type="xs:string"/&gt;
        &lt;xs:attribute ref="xlink:href" use="optional"/&gt;
        &lt;xs:attribute ref="xlink:type" use="optional"/&gt;
    &lt;/xs:attributeGroup&gt;
    &lt;xs:element name="translateRule" type="its:translateRule.type"/&gt;
    &lt;xs:complexType name="translateRule.type"&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="translate" use="required" type="its:translate.type"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="locNoteRule" type="its:locNoteRule.type"/&gt;
    &lt;xs:complexType name="locNoteRule.type"&gt;
        &lt;xs:sequence minOccurs="0" maxOccurs="1"&gt;
            &lt;xs:element ref="its:locNote"/&gt;
        &lt;/xs:sequence&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="locNotePointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="locNoteType" use="required" type="its:locNoteType.type"/&gt;
        &lt;xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/&gt;
        &lt;xs:attribute name="locNoteRefPointer" type="xs:string" use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="locNote" type="its:locNote.type"/&gt;
    &lt;xs:complexType name="locNote.type" mixed="true"&gt;
        &lt;xs:attribute name="translate" use="optional" type="its:translate.type"/&gt;
        &lt;xs:attribute name="locNote" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="locNoteType" use="optional" type="its:locNoteType.type"/&gt;
        &lt;xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/&gt;
        &lt;xs:attribute name="termInfoRef" type="xs:anyURI" use="optional"/&gt;
        &lt;xs:attribute name="term" use="optional" type="its:term.type"/&gt;
        &lt;xs:attribute name="dir" use="optional" type="its:dir.type"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="termRule"/&gt;
    &lt;xs:complexType name="termRule.type"&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="term" type="its:term.type" use="required"/&gt;
        &lt;xs:attribute name="termInfoRef" type="xs:anyURI" use="optional"/&gt;
        &lt;xs:attribute name="termInfoRefPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="termInfoPointer" type="xs:string" use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="dirRule" type="its:dirRule.type"/&gt;
    &lt;xs:complexType name="dirRule.type"&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="dir" type="its:dir.type" use="required"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="rubyRule"/&gt;
    &lt;xs:complexType name="rubyRule.type"&gt;
        &lt;xs:sequence&gt;
            &lt;xs:element ref="its:rubyText"/&gt;
        &lt;/xs:sequence&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="rubyPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="rtPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="rpPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="rbcPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="rtcPointer" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="rbspanPointer" type="xs:string" use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="rubyText" type="its:rubyText.type"/&gt;
    &lt;xs:complexType name="rubyText.type" mixed="true"&gt;
        &lt;xs:attribute name="translate" type="its:translate.type" use="optional"/&gt;
        &lt;xs:attribute name="locNote" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="locNoteType" type="its:locNoteType.type" use="optional"/&gt;
        &lt;xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/&gt;
        &lt;xs:attribute name="term" type="its:term.type" use="optional"/&gt;
        &lt;xs:attribute name="termInfoRef" type="xs:string" use="optional"/&gt;
        &lt;xs:attribute name="dir" type="its:dir.type" use="optional"/&gt;
        &lt;xs:attribute name="rbspan" type="xs:string" use="optional"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="langRule"/&gt;
    &lt;xs:complexType name="langRule.type"&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="langPointer" type="xs:string" use="required"/&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:element name="withinTextRule"/&gt;
    &lt;xs:complexType name="withinTextRule.type"&gt;
        &lt;xs:attributeGroup ref="its:its.Selector.attlist"/&gt;
        &lt;xs:attribute name="withinText" type="its:withinText.type"/&gt;
    &lt;/xs:complexType&gt;
&lt;/xs:schema&gt;</pre></div></div><p>The following is a driver file which can be used to evoke the schema above.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4523" id="d4e4523"></a>Example 41: </div><div class="exampleInner"><pre>&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:xhtml="http://www.w3.org/1999/xhtml"
    targetNamespace="http://www.w3.org/1999/xhtml"
    xmlns:its="http://www.w3.org/2005/11/its"
    xmlns="http://www.w3.org/1999/xhtml" blockDefault="#all"&gt;
    &lt;xs:annotation&gt;
        &lt;xs:documentation&gt; This is the XML Schema Driver for new Document Type
         XHTML Basic 1.0 + ITS
         $Id: Overview.html,v 1.10 2008/02/12 04:55:09 fsasaki Exp $
        &lt;/xs:documentation&gt;
        &lt;xs:documentation
         source="http://www.w3.org/TR/xml-i18n-bp/#integration-its-xhtmlmod"/&gt;
    &lt;/xs:annotation&gt;
    &lt;xs:import namespace="http://www.w3.org/2005/11/its"
     schemaLocation="its-module.xsd"/&gt;
    &lt;xs:redefine schemaLocation="xhtml-schemas/xhtml-basic10.xsd"&gt;
        &lt;xs:group name="HeadOpts.mix"&gt;
            &lt;xs:choice&gt;
                &lt;xs:group ref="HeadOpts.mix"/&gt;
                &lt;xs:element ref="its:rules"/&gt;
            &lt;/xs:choice&gt;
        &lt;/xs:group&gt;
        &lt;xs:attributeGroup name="Common.attrib"&gt;
            &lt;xs:attributeGroup ref="Common.attrib"/&gt;
            &lt;xs:attributeGroup ref="its:its.ITSLocal.attlist"/&gt;
        &lt;/xs:attributeGroup&gt;
    &lt;/xs:redefine&gt;
&lt;/xs:schema&gt;</pre></div></div><p>The file below is an instance which can be validated against this schema.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4528" id="d4e4528"></a>Example 42: </div><div class="exampleInner"><pre>&lt;html xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:its="http://www.w3.org/2005/11/its"&gt;
    &lt;head&gt;
        &lt;title&gt; &lt;/title&gt;
        &lt;its:rules version="1.0"&gt;
            &lt;its:locNoteRule locNoteType="alert" selector="..." locNoteRef="..."&gt;
            &lt;/its:locNoteRule&gt;
            &lt;its:locNoteRule locNoteType="alert" selector="..."&gt;
                &lt;its:locNote&gt; &lt;/its:locNote&gt;
            &lt;/its:locNoteRule&gt;
            &lt;its:termRule selector="..." term="yes"/&gt;
        &lt;/its:rules&gt;
    &lt;/head&gt;
    &lt;body&gt;
        &lt;h3&gt; &lt;/h3&gt;
        &lt;table&gt;
            &lt;tr&gt;
                &lt;td&gt; &lt;/td&gt;
            &lt;/tr&gt;
        &lt;/table&gt;
        &lt;ul&gt;
            &lt;li its:locNote="..." its:translate="no"&gt; &lt;/li&gt;
        &lt;/ul&gt;
    &lt;/body&gt;
&lt;/html&gt;</pre></div></div></div><div class="div4">
<h5><a name="integration-its-xhtmlmod-cs" id="integration-its-xhtmlmod-cs"></a>5.1.2.3Conformance statement</h5><p>This schema conforms to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance Type 1</a> of the ITS specification.</p><p>The schema adds the following ITS element to the XHTML schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li></ul><p>The schema adds the following local ITS attributes to the XHTML schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code></p></li></ul></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="integration-its-xhtml-nvdl" id="integration-its-xhtml-nvdl"></a>5.1.3 Using NVDL to integrate ITS into XHTML</h4><p>As you have seen in the previous section it might sometimes be quite
laborious to integrate ITS into an existing vocabulary using only
modularization and the customization features of particular schema
language. In such situations you can use the NVDL schema language
instead.</p><p>In NVDL you can create a sort of "meta-schema" which defines how to
combine and provide additional rules for existing schemas. An NVDL schema can be used in the same
way as schemas written in other languages, such as DTDs, RELAX NG or XML
Schema. You can then use such a schema to validate your document
instances or so that an XML editor can guide you while you are editing
documents. The <a href="http://nvdl.org/">NVDL.org site</a> provides
additional information about the language. You can also find there a  list
of applications which support the NVDL language.</p><p>Adding ITS to XHTML involves allowing the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element
inside the <code>head</code> element and allowing the ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#span.attributes">local
attributes</a> to appear on every existing XHTML element.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-xhtml-its-nvdl" id="EX-xhtml-its-nvdl"></a>Example 43: NVDL script for XHTML with  ITS</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0"
       startMode="xhtml"&gt;

  &lt;!-- Validation starts here --&gt;
  &lt;mode name="xhtml"&gt;
    &lt;!-- XHTML elements are validated against XHTML schema --&gt;
    &lt;namespace ns="http://www.w3.org/1999/xhtml"&gt;
      &lt;validate schema="../xhtml-schemas/xhtml11.xsd"&gt;
        &lt;!-- Inside head element its:rules element is allowed --&gt;
        &lt;context path="head" useMode="its-rules"/&gt;
      &lt;/validate&gt;
    &lt;/namespace&gt;

    &lt;!-- ITS attributes are validated against separate schema --&gt;
    &lt;namespace ns="http://www.w3.org/2005/11/its" match="attributes"&gt;
      &lt;validate schema="its-attributes-for-xhtml.rng"/&gt;
    &lt;/namespace&gt;
  &lt;/mode&gt;

  &lt;!-- Handling of ITS markup in head is different 
       because its:rules should be allowed --&gt;
  &lt;mode name="its-rules"&gt;
    &lt;namespace ns="http://www.w3.org/2005/11/its"&gt;
      &lt;validate schema="its-rules.rng"/&gt;   
    &lt;/namespace&gt;
    &lt;namespace ns="http://www.w3.org/2005/11/its" match="attributes"&gt;
      &lt;validate schema="its-attributes-for-xhtml.rng"/&gt;
    &lt;/namespace&gt;
  &lt;/mode&gt;
&lt;/rules&gt;</pre><p>[<a href="nvdl/xhtml-its.nvdl">Example's source code</a>]</p></div><p>The NVDL script references three schemas. One for XHTML and two
supplementary ones for ITS. The first supplementary schema defines local
attributes which are needed for XHTML.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-its-attributes-for-xhtml" id="EX-its-attributes-for-xhtml"></a>Example 44: Schema defining ITS local attributes suitable for XHTML</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;grammar xmlns="http://relaxng.org/ns/structure/1.0"&gt;

  &lt;!-- Include schema with all ITS building blocks --&gt;  
  &lt;include href="its.rng"/&gt;
  
  &lt;!-- Pull out only definitions of ITS attributes 
       which are useful for XHTML --&gt;
  &lt;start&gt;
    &lt;group&gt;
      &lt;ref name="its-att.translate.attributes"/&gt;
      &lt;ref name="its-att.locNote.attributes"/&gt;
      &lt;ref name="its-att.term.attributes"/&gt;
      &lt;optional&gt;
        &lt;ref name="its-att.version.attributes"/&gt;
      &lt;/optional&gt;
    &lt;/group&gt;
  &lt;/start&gt;
  
&lt;/grammar&gt;</pre><p>[<a href="nvdl/its-attributes-for-xhtml.rng">Example's source code</a>]</p></div><p>The second supplementary schema defines the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-its-rules" id="EX-its-rules"></a>Example 45: Schema defining ITS local attributes suitable for XHTML</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;grammar xmlns="http://relaxng.org/ns/structure/1.0"&gt;

  &lt;!-- Include schema with all ITS building blocks --&gt;  
  &lt;include href="its.rng"/&gt;

  &lt;!-- Pull out only definition of its:rules element --&gt;
  &lt;start&gt;
    &lt;ref name="its-rules"/&gt;
  &lt;/start&gt;

&lt;/grammar&gt;</pre><p>[<a href="nvdl/its-rules.rng">Example's source code</a>]</p></div><div class="div4">
<h5><a name="integration-its-xhtml-nvdl-cs" id="integration-its-xhtml-nvdl-cs"></a>5.1.3.1Conformance statement</h5><p>This schema conforms to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance
Type 1</a> of the ITS specification.</p><p>The schema adds the following ITS element to the XHTML schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li></ul><p>The schema adds the following local ITS attributes to the  XHTML schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code></p></li></ul></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="relating-its-plus-xhtml" id="relating-its-plus-xhtml"></a>5.1.4 Associating existing XHTML markup with ITS</h4><p>A number of XHTML constructs implement the same semantics as some of the ITS data categories. In addition, some of the attributes in XHTML need to be translated, which is not the default for XML documents according to the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#datacategories-defaults-etc">default translate settings in ITS</a>. These attributes need to be identified as needing translation.</p><p>An external ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">rules</a> element can summarize these relationships. Because XHTML use is widespread and covers a large amount of legacy material the rules defined here may not be optimal for everyone.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-relating-its-plus-xhtml-1" id="EX-relating-its-plus-xhtml-1"></a>Example 46: External ITS rules for XHTML documents</div><div class="exampleInner"><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"
 xmlns:h="http://www.w3.org/1999/xhtml"&gt;

 &lt;!-- special content. (See note 1) --&gt;
 &lt;its:translateRule selector="//h:script" translate="no"/&gt;
 &lt;its:translateRule selector="//h:style" translate="no"/&gt;

 &lt;!-- Normal translatable attributes --&gt;
 &lt;its:translateRule selector="//h:*/@abbr" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:*/@accesskey" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:*/@alt" translate="yes"/&gt;

 &lt;its:translateRule selector="//h:*/@prompt" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:*/@standby" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:*/@summary" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:*/@title" translate="yes"/&gt;

 &lt;!-- The input element (Important: See note 2) --&gt;
 &lt;its:translateRule selector="//h:input/@value" translate="yes"/&gt;
 &lt;its:translateRule selector="//h:input[@type='hidden']/@value" translate="no"/&gt;

 &lt;!-- Non-translatable element (See note 3) --&gt;

 &lt;its:translateRule selector="//h:del" translate="no"/&gt;
 &lt;its:translateRule selector="//h:del/descendant-or-self::*/@*" translate="no"/&gt;

 &lt;!-- Often-used translatable meta content. --&gt;
 &lt;its:translateRule selector="//h:meta[@name='keywords']/@content"
		    translate="yes"/&gt;
 &lt;its:translateRule selector="//h:meta[@name='description']/@content"
		    translate="yes"/&gt;

 &lt;!-- Possible term (Important: See note 4) --&gt;
 &lt;its:termRule selector="//h:dt" term="yes"/&gt;

 &lt;!-- Bidirectional information --&gt;
 &lt;its:dirRule selector="//h:*[@dir='ltr']" dir="ltr"/&gt;
 &lt;its:dirRule selector="//h:*[@dir='rtl']" dir="rtl"/&gt;
 &lt;its:dirRule selector="//h:bdo[@dir='ltr']" dir="lro"/&gt;
 &lt;its:dirRule selector="//h:bdo[@dir='rtl']" dir="rlo"/&gt;

 &lt;!-- Elements within text --&gt;
 &lt;its:withinTextRule withinText="yes"
  selector="//h:abbr | //h:acronym | //h:br | //h:cite | //h:code | //h:dfn
  | //h:kbd | //h:q | //h:samp | //h:span | //h:strong | //h:var | //h:b | //h:em
  | //h:big | //h:hr | //h:i | //h:small | //h:sub | //h:sup | //h:tt | //h:del
  | //h:ins | //h:bdo | //h:img | //h:a | //h:font | //h:center | //h:s | //h:strike
  | //h:u | //h:isindex" /&gt;

&lt;/its:rules&gt;</pre></div><p>[<a href="EX-relating-its-plus-xhtml-1.xml">Example's source code</a>]</p></div><p>Additional notes on these rules:</p><ol class="depth1"><li><p>The <code>script</code> and <code>style</code> elements may contain  text that needs translation, but their content needs to be parsed with, respectively, a script filter and a CSS filter. Depending on the capabilities of your translation tools you may want to leave these elements as needing translation.</p></li><li><p>The <code>value</code> attribute of the <code>input</code> element may or may not need translation, depending on the way the element is used. The decision as to whether the value of this attribute needs translation or not will depend on its use in a given instance.  Note, however, that it can often be undesirable to translate these values, since they are commonly used by scripts as identifiers: change the value of the attribute and the script will often fail.  The values of the <code>value</code> attribute are not usually seen by a user of a web page.</p></li><li><p>The <code>del</code> element indicates removed text and therefore, most often, its content would not be translated. Because ITS rules for elements are not inherited by attributes, and because this element may contain elements with  attributes that need translation, such as <code>img</code> with an <code>alt</code> attribute, you need to: a) define this rule after defining how translation applies to attribute values, and b) use  rules such as <code>selector="//h:del/descendant-or-self::*/@*"</code> to override any possibility of translation being applied to an  attribute within a <code>del</code> element or any of its descendants.</p></li><li><p>The <code>dt</code> element is defined by HTML as a "definition term" and can therefore be seen as a candidate to be associated with the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#terminology">ITS Terminology data category</a>. However, for historical reasons, this element has been used for many other purposes. Whether or not <code>dt</code> is associated with the ITS term data category will depend on its use in a given instance.</p></li></ol></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="tei-modularization" id="tei-modularization"></a>5.2 ITS and TEI</h3><p>The <cite>Text Encoding Initiative</cite> <a title="Text Encoding Initiative Guidelines development version (P5)" href="#tei">[TEI]</a> is intended for literary and linguistic material, and is most often used for digital editions of existing printed material. It is also suitable, however, for general purpose writing. The P5 release of TEI consists of 23 modules which can be combined together as needed.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="tei-plus-its" id="tei-plus-its"></a>5.2.1 Integrating ITS into TEI</h4><p>TEI is maintained as a single ODD document, and customizations of it are also written as ODD documents. ODD (<em>One Document Does it all</em>) is a literate programming language of the Text Encoding Initiative for writing XML schemas. These documents are processed using XSLT style sheets to make a tailored user-level schema in XML DTD, XML Schema or RELAX NG.</p><p>The ITS additions involve two changes to TEI:</p><ol class="depth1"><li><p>Allowing <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">rules</a></code> to appear in the TEI metadata section (the <code>teiHeader</code>).</p></li><li><p>Adding the ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#span.attributes">local attributes</a> to the TEI global attribute set.</p></li></ol><p>Both of these can be easily achieved using standard techniques in ODD.</p><p>The body of a TEI+ITS customization consists of a <code>schemaSpec</code> which lists the modules to be included (this example includes six common ones):</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4807" id="d4e4807"></a>Example 47: A <code>schemaSpec</code> element with modules to be included</div><pre>&lt;schemaSpec ident="tei-its" start="TEI"&gt;
 &lt;moduleRef key="header"/&gt;
 &lt;moduleRef key="core"/&gt;
 &lt;moduleRef key="tei"/&gt;
 &lt;moduleRef key="textstructure"/&gt;
 &lt;moduleRef key="namesdates"/&gt;
 &lt;moduleRef key="msdescription"/&gt; 
 &lt;!-- Etc. --&gt;
&lt;/schemaSpec&gt;</pre><p>[<a href="EX-tei-plus-its-1.xml">Example's source code</a>]</p></div><p>In addition, we load the ITS schema (in its RELAX NG XML format, the language used by TEI for expressing content models), and overload the definition of the TEI content class <code>model.headerPart</code> to include the ITS <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">rules</a></code>:</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4828" id="d4e4828"></a>Example 48: Inclusion of ITS <code>rules</code> into the TEI schema</div><pre>&lt;moduleRef url="its.rng"&gt;
 &lt;content xmlns:rng="http://relaxng.org/ns/structure/1.0"&gt;
 &lt;rng:define name="model.headerPart" combine="choice"&gt;
  &lt;rng:ref name="rules"/&gt;
 &lt;/rng:define&gt;
 &lt;/content&gt;
&lt;/moduleRef&gt;</pre><p>[<a href="EX-tei-plus-its-2.xml">Example's source code</a>]</p></div><p>The content class determines which elements are allowed as children of <code>teiHeader</code>. Lastly, we change the definition of the global attribute class <code>att.global</code> to reference the ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#span.attributes">local attributes</a> (available from the ITS schema we loaded earlier):</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4851" id="d4e4851"></a>Example 49: Addition of the ITS local attributes to the global attributes</div><pre>&lt;classSpec ident="att.global" type="atts" mode="change"&gt;
 &lt;attList&gt;
  &lt;attRef name="span.attributes"/&gt;
 &lt;/attList&gt;
&lt;/classSpec&gt;</pre><p>[<a href="EX-tei-plus-its-3.xml">Example's source code</a>]</p></div><p>When processing, this customization produces a schema which permits markup like this:</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e4863" id="d4e4863"></a>Example 50: Document which is valid against a schema TEI+ITS</div><pre>&lt;TEI xmlns:its="http://www.w3.org/2005/11/its" xmlns="http://www.tei-c.org/ns/1.0"&gt;
 &lt;teiHeader&gt;
  &lt;fileDesc&gt;
   &lt;!-- details of the file --&gt;
  &lt;/fileDesc&gt;
  &lt;rules xmlns="http://www.w3.org/2005/11/its" version="1.0"
   xmlns:t="http://www.tei-c.org/ns/1.0"&gt;
   &lt;translateRule translate="no" selector="//t:body/t:p/@*"/&gt;
   &lt;translateRule translate="yes" selector="//t:body/t:p"/&gt;
  &lt;/rules&gt;
 &lt;/teiHeader&gt;
 &lt;text&gt;
  &lt;body&gt;
   &lt;p rend="normal"&gt;Hello &lt;hi&gt;world&lt;/hi&gt;
   &lt;/p&gt;
   &lt;p rend="special"&gt;Goodbye&lt;/p&gt;
   &lt;p its:translate="no"&gt;This must not be translated&lt;/p&gt;
  &lt;/body&gt;
 &lt;/text&gt;
&lt;/TEI&gt;</pre><p>[<a href="EX-tei-plus-its-4.xml">Example's source code</a>]</p></div><p>In this example, a set of rule elements are provided in the
  header to provide rules, and the body of the text performs
  a specific override.</p><div class="div4">
<h5><a name="tei-modularization-cs" id="tei-modularization-cs"></a>5.2.1.1Conformance statement</h5><p>This schema conforms to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance
Type 1</a> of the ITS specification.</p><p>The schema adds the following ITS element to the  TEI schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li></ul><p>The schema adds the following local ITS attributes to the  TEI schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code></p></li></ul></div></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="xmlspec" id="xmlspec"></a>5.3 ITS and XML Spec</h3><p>The XML Spec format <a title="The XML Spec Schema and Stylesheets" href="#xmlspecbib">[XML Spec]</a> is intended for W3C Working Drafts, Notes, Recommendations, and all other document types that fall under the category of technical reports. XML Spec is available in the following formats: XML DTD, XML Schema and RELAX NG.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="its-xmlspec" id="its-xmlspec"></a>5.3.1 Integration of ITS into XML Spec</h4><p>The text below takes <a href="http://www.w3.org/2002/xmlspec/#spec210">version 2.10 of XML Spec</a> as an example and shows how you would integrate ITS into it.  This version is available in <a href="http://www.w3.org/2002/xmlspec/dtd/2.10/xmlspec.dtd">DTD</a>, <a href="http://www.w3.org/2002/xmlspec/xsd/2.10/xmlspec.xsd">XML Schema</a> and <a href="http://www.w3.org/2002/xmlspec/rng/2.10/xmlspec.rnc">RELAX NG</a> formats.</p><div class="note"><p><span class="note-head">Note: </span>Within the <a href="http://www.w3.org/International/">W3C Internationalization Activity</a>, a <a href="http://www.w3.org/International/xmlspec/documentation/xmlspec-i18n-dtd.html">modified version of the XML Spec 2.9 DTD</a> is used for document creation. This version has  been updated with ITS markup declarations.</p></div><p>The <em>integration of ITS into the XML Spec DTD</em> uses the files <a href="xmlspec/xmlspec-its.dtd">xmlspec-its.dtd</a> (the XML Spec schema) and <a href="xmlspec/its.dtd">its.dtd</a> (the ITS schema). To achieve the integration, the following modifications to the XML Spec DTD have been made:</p><ol class="depth1"><li><p>External ITS definitions are integrated via the new entity <code>&lt;!ENTITY % its SYSTEM "its.dtd"&gt;</code> and the entity call <code>%its;</code>.</p></li><li><p>The existing XML Spec entity <code>%local.common.att;</code> has been modified. It now includes the declarations <code>'%its.att.local.with-ns.attributes;</code> and <code>
xmlns:its CDATA "http://www.w3.org/2005/11/its"</code>. The former allows the use of  ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#span.attributes">local attributes</a>, the latter is necessary to permit the use of the ITS namespace in the DTD.</p></li><li><p>The XML Spec entity <code>%header.mdl;</code> contains the content model of the <code>header</code> element. The ITS  <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a> element</code> has been added as the last element to this content model. In this way, <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> can be used inside an XML Spec document.</p></li><li><p>The ITS elements <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> and <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code> have been added to the XML Spec entity <code>%p.pcd.mix;</code>. In this way it is possible to use them as inline elements.</p></li></ol><p>The <em>integration of ITS into the XML Spec RELAX NG schema</em> uses the files <a href="xmlspec/xmlspec-its.rnc">xmlspec-its.rnc</a> (the XML Spec schema) and <a href="xmlspec/its.rnc">its.rnc</a> (the ITS schema). The modifications to the RELAX NG schema have the same motivations  like for the DTD described above. The modifications are:</p><ol class="depth1"><li><p>External ITS definitions are integrated via the statement <code>include "its.rnc"</code>.</p></li><li><p>The pattern <code>its-att.local.with-ns.attributes</code> is referenced from the pattern <code>local.common.att</code>.</p></li><li><p>The pattern <code>its-rules</code> is referenced from the pattern <code>header.mdl</code>.</p></li><li><p>The patterns <code>its-ruby</code> and <code>its-span</code> are referenced from the pattern <code>p.pcd.mix</code>.</p></li></ol><p>The <em>integration of ITS into the XML Spec XML Schema schema</em> uses the files <a href="xmlspec/xmlspec-its.xsd">xmlspec-its.xsd</a> (the XML Spec schema), <a href="xmlspec/its.xsd">its.xsd</a> (the ITS schema), <a href="xmlspec/xml.xsd">xml.xsd</a> (for declarations from the <a href="http://www.w3.org/XML/1998/namespace">XML namespace</a>) and <a href="xmlspec/xlink.xsd">xlink.xsd</a> (for declarations from the <a href="http://www.w3.org/1999/xlink">XLink namespace</a>). The modifications to the XML Spec XML Schema schema have the same motivations like for the DTD described above. The modifications are:</p><ol class="depth1"><li><p>External ITS definitions are integrated via an  <code>&lt;xs:import&gt;</code> statement.</p></li><li><p>The attribute group <code>its-att.local.with-ns.attributes</code> is added to the attribute group <code>common.att</code>.</p></li><li><p>The element declaration <code>its:rules</code> is added to the element group <code>header.mdl</code>.</p></li><li><p>The element declarations <code>its:ruby</code> and <code>its:span</code> are added to the element group <code>p.pcd.mix</code>.</p></li></ol><p>The following example shows an XML Spec document conforming to the XML Spec+ITS schemas.  The <a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a> element is used to indicate that elements for code, keywords and examples should not be translated. The <code>w3c-doctype</code> element is also marked as non-translatable using local ITS markup.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-xmlspec-plus-its.xml" id="EX-xmlspec-plus-its.xml"></a>Example 51: Sample XML Spec document with ITS markup</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;spec xmlns:its="http://www.w3.org/2005/11/its"&gt;
    &lt;header&gt;
        &lt;title&gt;Best Practices for XML Internationalization&lt;/title&gt;
        &lt;w3c-designation&gt;...&lt;/w3c-designation&gt;
        &lt;w3c-doctype its:translate="no"&gt;W3C Working Draft&lt;/w3c-doctype&gt;
        &lt;pubdate&gt;
            &lt;day&gt;5&lt;/day&gt;
            &lt;month&gt;December&lt;/month&gt;
            &lt;year&gt;2007&lt;/year&gt;
        &lt;/pubdate&gt;
        &lt;publoc&gt;
            &lt;loc href="..." &gt;...&lt;/loc&gt;
        &lt;/publoc&gt;
        &lt;latestloc&gt;
            &lt;loc href="..."&gt;...&lt;/loc&gt;
        &lt;/latestloc&gt;
        &lt;prevlocs&gt;
            &lt;loc href="..."
                &gt;...&lt;/loc&gt;
        &lt;/prevlocs&gt;
        &lt;authlist&gt;
            &lt;author&gt;
                &lt;name&gt;...&lt;/name&gt;
                &lt;affiliation&gt;...&lt;/affiliation&gt;
            &lt;/author&gt;
        &lt;/authlist&gt;
        &lt;abstract&gt;
            &lt;p&gt;This document provides a set of guidelines for ...&lt;/p&gt;
        &lt;/abstract&gt;
        &lt;status&gt;
            &lt;p/&gt;
        &lt;/status&gt;
        &lt;langusage&gt;
            &lt;language id="en"&gt;en&lt;/language&gt;
        &lt;/langusage&gt;
        &lt;revisiondesc&gt;
            &lt;p&gt;This is an updated version of this document.&lt;/p&gt;
        &lt;/revisiondesc&gt;
        &lt;its:rules version="1.0"&gt;
            &lt;its:translateRule selector="//code | //kw //eg" translate="no"/&gt;
        &lt;/its:rules&gt;
    &lt;/header&gt;
    &lt;body&gt;
        &lt;div1 id="idIntro"&gt;
            &lt;head&gt;Introduction&lt;/head&gt;
            &lt;p&gt;This document is a complement  ...&lt;/p&gt;
        &lt;/div1&gt;
    &lt;/body&gt;
    &lt;back&gt;
        &lt;div1&gt;
            &lt;head&gt;References&lt;/head&gt;
        &lt;/div1&gt;
        &lt;inform-div1&gt;
            &lt;head&gt;Acknowledgements&lt;/head&gt;
        &lt;/inform-div1&gt;
    &lt;/back&gt;
&lt;/spec&gt;</pre><p>[<a href="xmlspec/ex-xmlspec-plus-its.xml">Example's source code</a>]</p></div><div class="div4">
<h5><a name="xmlspec-plus-its-cs" id="xmlspec-plus-its-cs"></a>5.3.1.1Conformance statement</h5><p>The three XML Spec schemas described above conform to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance
Type 1</a> of the ITS specification.</p><p>The following ITS elements are added:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code></p></li></ul><p>The following local ITS attributes are added:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code></p></li></ul></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="relating-xmlspec-plus-its" id="relating-xmlspec-plus-its"></a>5.3.2 Associating existing XML Spec markup with ITS</h4><p>A number of XML Spec constructs implement the same semantics as some
of the ITS data categories. In addition, some of the XML Spec
attribute values need to be translated, which is not the default for XML
documents according to the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#datacategories-defaults-etc">ITS default
settings for translatability</a>. These attributes need to be
identified as needing translation, and some elements need to be identified as not needing translation.</p><div class="note"><p><span class="note-head">Note: </span>When you have the choice of using an XML Spec construct or an ITS
construct to express the same semantics, make sure you use the XML Spec
construct to ensure that XML Spec processing tools work properly. Use ITS local
markup only if XML Spec does not provide an equivalent.</p></div><p>An external ITS <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element can
summarize these relationships. The rules defined here are just examples and  may need further
tailoring for specific use.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-relating-xmlspec-plus-its" id="EX-relating-xmlspec-plus-its"></a>Example 52: ITS external rules for XML Spec documents</div><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its"
 xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0"&gt;
 
 &lt;!-- Translatable attributes --&gt;
 &lt;its:translateRule selector="//graphic/@alt | //table/@summary | //term
  | //termdef | //key-term" translate="yes"/&gt;

 &lt;!-- Non-translatable elements/attributes --&gt;
 &lt;its:translateRule translate="no"
  selector="//version | // w3c-designation | w3c-doctype | //publoc | //altlocs
  | //prevlocs | //latestloc | //errataloc | //preverrataloc | //translationloc
  | //authlist | //author | //name | //affiliation | //email | //langusage
  | //language | //graphic | //proto | //arg | //scrap | //prodgroup | //prod
  | //lhs | //rhs | //wfc | //vc | //constraint | //bnf | //prodrecap
  | //interface | //module | //reference | //typedef | // struct | //component
  | //union | //case | //enum | //enumerator | //sequence | //constant
  | //exception | //attribute | //method | //parameters | //param | //returns
  | //raises | //typename | //att | //attval | //bibref | //code | //el | //kw
  | //nt | //var | //xnt | //key-term"/&gt;

 &lt;!-- Possible terms --&gt;
 &lt;its:termRule selector="//label | //def" term="yes"/&gt;

 &lt;!-- Elements within text --&gt;
 &lt;its:withinTextRule withinText="yes" selector="//abbr | //att | //attval
  | //code | //eg | //emph | //ins | //kw | //loc | //note | //qterm
  | //phrase | //quote"/&gt;
 &lt;its:withinTextRule withinText="nested" selector="//footnote
  | //termdef | //its:ruby"/&gt;

&lt;/its:rules&gt;</pre><p>[<a href="xmlspec/ex-relating-xmlspec-plus-its-1.xml">Example's source code</a>]</p></div></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="dita" id="dita"></a>5.4 ITS and DITA</h3><p>The <cite>Darwin Information Typing Architecture</cite> <a title="OASIS Darwin Information Typing&#xA;Architecture (DITA) Language Specification v1.0" href="#dita10">[DITA 1.0]</a> is an XML-based architecture for authoring, producing, and delivering readable information as discrete, typed topics.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="its-dita" id="its-dita"></a>5.4.1 Integration of ITS into DITA</h4><p>DITA offers some of the ITS features by default (See <a class="section-ref" href="#dita-its-relating">Section 5.4.2: Associating existing DITA markup with ITS</a> for more information on that). In  some cases, however,  you may still want to allow the use of ITS markup directly in your DITA documents. For example, the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute, or the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element. DITA provides a way to create a domain specialization based on the <code>foreign</code> element and attribute extension points.</p><p>For example, the DITA Concept DTD can be extended as follows:</p><p>First, create two files for the ITS domain specialization. The first one <code>itsDomain.ent</code> contains the entity definitions that will be used in the extended DTD.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e5271" id="d4e5271"></a>Example 53: Content of the <code>itsDomain.ent</code> file</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!ENTITY % its-d-foreign "its"           &gt;
&lt;!ENTITY   its-d-att     "(topic its-d)" &gt;</pre><p>[<a href="dita/itsDomain.ent">Example's source code</a>]</p></div><p>The second file, <code>itsDomain.mod</code>, contains the definition of the element where the ITS markup will be placed.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e5288" id="d4e5288"></a>Example 54: Content of the <code>itsDomain.mod</code> file</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!-- declaration for the specialized wrapper and alternate element --&gt;
&lt;!ENTITY % its "its"&gt;

&lt;!-- definition for the specialized wrapper and alternate element --&gt;
&lt;!ELEMENT its ((%its-rules;) | (%its-ruby;)) &gt;
&lt;!ATTLIST its %global-atts;
          class CDATA "+ topic/foreign its-d/its "&gt;</pre><p>[<a href="dita/itsDomain.mod">Example's source code</a>]</p></div><p>Then you can adapt the <code>concept.dtd</code> file to take into account the new domain.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e5305" id="d4e5305"></a>Example 55: The DITA Concept DTD modified for ITS</div><p>Include the ITS domain entities at the end of the Domain Entity Declarations section:</p><div class="exampleInner"><pre>&lt;!ENTITY % its-d-dec SYSTEM "itsDomain.ent" &gt;
  %its-d-dec;</pre></div><p>Include the ITS document type and namespace:</p><div class="exampleInner"><pre>&lt;!ENTITY % its-def SYSTEM  "its.dtd" &gt;
  %its-def;
&lt;!ENTITY % its-d-namespace "xmlns:its CDATA #FIXED 'http://www.w3.org/2005/11/its'"&gt;
&lt;!ENTITY % props-attribute-extensions  ""                            &gt;
&lt;!ENTITY % base-attribute-extensions   "%its-d-namespace;
  %att.version.attributes;
  %att.locNote.attributes;" &gt;</pre></div><p>Define the extension element at the end of the Domain Extension section:</p><div class="exampleInner"><pre>&lt;!ENTITY % foreign "foreign | %its-d-foreign;" &gt;</pre></div><p>Modify the list of included domains in the included-domains entity:</p><div class="exampleInner"><pre>&lt;!ENTITY included-domains
  "&amp;ui-d-att; &amp;hi-d-att; &amp;pr-d-att; &amp;sw-d-att;
  &amp;ut-d-att; &amp;indexing-d-att; &amp;its-d-att;" &gt;</pre></div><p>Include the ITS domain module at the end of the Domain Element Integration section:</p><div class="exampleInner"><pre>&lt;!ENTITY % its-d-def SYSTEM "itsDomain.mod" &gt;
  %its-d-def;</pre></div><p>[<a href="dita/itsConcept.dtd">Example's source code</a>]</p></div><p>All these changes allow you to include a new <code>its</code> element in different parts of the DITA document and use ITS-defined constructs where DITA may be missing support, such as for ruby text. This also allows you to use a selection of ITS-defined attributes to complement what DITA already provides.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-dita-plus-its.xml" id="EX-dita-plus-its.xml"></a>Example 56: DITA document with ITS</div><p>This DITA document includes the following ITS constructs:</p><ul><li><p>An <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element is added to the <code>prolog</code> element to specify that, in the scope of this document, the content of <code>uicontrol</code> elements is not to be translated.</p></li><li><p>The second <code>p</code> element includes a <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code> attribute that applies to its content.</p></li><li><p>The last paragraph includes an <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> element.</p></li></ul><pre>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
 "dtd/itsConcept.dtd"&gt;
&lt;concept id="DITAwithITS" xml:lang="en"
 xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"&gt;
 &lt;title&gt;Using ITS in DITA&lt;/title&gt;
 &lt;prolog&gt;
  &lt;its&gt;
   &lt;its:rules&gt;
    &lt;its:translateRule selector="ui" translate="no"/&gt;
   &lt;/its:rules&gt;
  &lt;/its&gt;
 &lt;/prolog&gt;
 &lt;conbody xml:lang="ja"&gt;
  &lt;p&gt;Example of applying global rules: Normal text with
   &lt;uicontrol&gt;non-translatable text&lt;/uicontrol&gt;.&lt;/p&gt;
  &lt;p its:locNote="Localization note"&gt;Text where the note applies.&lt;/p&gt;
  &lt;p&gt;Example of ruby text:
   &lt;ph xml:lang="ja"&gt;この本は &lt;its&gt;&lt;its:ruby&gt;
    &lt;its:rb&gt;慶応義塾大学&lt;/its:rb&gt;
    &lt;its:rp&gt;(&lt;/its:rp&gt;
    &lt;its:rt&gt;けいおうぎじゅくだいがく&lt;/its:rt&gt;
    &lt;its:rp&gt;)&lt;/its:rp&gt;
   &lt;/its:ruby&gt;&lt;/its&gt;/の歴史を説明するものです。&lt;/ph&gt;
  &lt;/p&gt;
 &lt;/conbody&gt;
&lt;/concept&gt;</pre><p>[<a href="dita/EX-dita-plus-its.xml">Example's source code</a>]</p></div><div class="div4">
<h5><a name="its-dita-cs" id="its-dita-cs"></a>5.4.1.1Conformance statement</h5><p>This schema conforms to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance
Type 1</a> of the ITS specification.</p><p>The schema adds the following ITS element to the DITA DTD:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code></p></li></ul><p>The schema adds the following local ITS attributes to the  DITA DTD:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.version">its:version</a></code></p></li></ul></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="dita-its-relating" id="dita-its-relating"></a>5.4.2 Associating existing DITA markup with ITS</h4><p>There are several ITS data categories that are already implemented in DITA. For example, DITA offers a <code>translate</code> attribute that provides the same functionality as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code>.</p><p>In the same way as for other formats, these existing features can be associated with ITS data categories, so ITS-enabled tools can process seamlessly DITA source documents.</p><div class="note"><p><span class="note-head">Note: </span>When you have the choice of using a DITA construct or an ITS construct to express the same thing, use the DITA construct to ensure that DITA processors work properly. Use ITS local markup only if DITA does not provide an equivalent.</p></div><div class="exampleOuter"><div class="exampleHeader"><a name="EX-dita-its-relating-1" id="EX-dita-its-relating-1"></a>Example 57: Associating DITA markup with ITS</div><pre>&lt;?xml version="1.0"?&gt;
&lt;!-- Possible default ITS rules for DITA --&gt;
&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;

 &lt;!-- Translatable attribute (some are deprecated) --&gt;
 &lt;its:translateRule selector="//image/@alt" translate="yes"/&gt;
 &lt;its:translateRule selector="//lq/@reftitle" translate="yes"/&gt;
 &lt;its:translateRule selector="//note/@othertype" translate="yes"/&gt;
 &lt;its:translateRule selector="//object/@standby" translate="yes"/&gt;
 &lt;its:translateRule selector="//othermeta/@content" translate="yes"/&gt;
 &lt;its:translateRule selector="//state/@value" translate="yes"/&gt;
 &lt;its:translateRule selector="//map/@title" translate="yes"/&gt;
 &lt;its:translateRule selector="//topicref/@navref" translate="yes"/&gt;
 &lt;its:translateRule selector="//topicgroup/@navtitle" translate="yes"/&gt;
 &lt;its:translateRule selector="//topichead/@navtitle" translate="yes"/&gt;
 &lt;its:translateRule selector="//data/@label" translate="yes"/&gt;

 &lt;!-- Non-translatable elements --&gt;
 &lt;its:translateRule selector="//draft-comment//*" translate="no"/&gt;
 &lt;its:translateRule selector="//draft-comment/descendant-or-self::*/@*"
  translate="no"/&gt;
 &lt;its:translateRule selector="//required-cleanup//*" translate="no"/&gt;
 &lt;its:translateRule selector="//required-cleanup/descendant-or-self::*/@*"
  translate="no"/&gt;
 &lt;its:translateRule selector="//coords" translate="no"/&gt;
 &lt;its:translateRule selector="//shape" translate="no"/&gt;

 &lt;!-- Translatability flags --&gt;
 &lt;its:translateRule selector="//*[@translate='no']" translate="no"/&gt;
 &lt;its:translateRule selector="//*[@translate='no']/descendant-or-self::*/@*"
  translate="no"/&gt;
 &lt;its:translateRule selector="//*[@translate='yes']" translate="yes"/&gt;

 &lt;!-- Directionality flags --&gt;
 &lt;its:dirRule selector="//*[dir='ltr']" dir="ltr"/&gt;
 &lt;its:dirRule selector="//*[dir='rtl']" dir="rtl"/&gt;
 &lt;its:dirRule selector="//*[dir='lro']" dir="lro"/&gt;
 &lt;its:dirRule selector="//*[dir='rlo']" dir="rlo"/&gt;

 &lt;!-- Elements within text (inline) --&gt;
 &lt;its:withinTextRule withinText="yes"
  selector="//boolean | //cite | //itemgroup | //keyword | //ph | //q |
   //state | //term | //tm | //xref | //b | //i | //sub | //sup | //tt |
   //u | //apiname | //codeph | //delim | //fragref | //kwd | //oper |
   //option | //parmname | //repsep | //sep | //synnoteref | //synph |
   //var | //cmdname | //filepath | //msgnum | //msgph | //systemoutput |
   //userinput | //varname | //menucascade | //shortcut | //uicontrol |
   //wintitle | //coords | //shape" /&gt;

 &lt;!-- The keyword elements within keywords are sub-flow, no in-line --&gt;
 &lt;its:withinTextRule withinText="nested" selector="//keywords/keyword" /&gt;

 &lt;!-- Elements within text (subflow) --&gt;
 &lt;its:withinTextRule withinText="nested"
  selector="//draft-comments | //required-cleanup | //alt | //fn |
  //indexterm" /&gt;   

 &lt;!-- Terminology --&gt;
 &lt;its:termRule selector="//term | //dt | //termindex" term="yes" /&gt;

&lt;/its:rules&gt;</pre><p>[<a href="dita/EX-dita-its-relating-1.xml">Example's source code</a>]</p></div><p>The declarations above cover different versions of DITA.</p></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="glade" id="glade"></a>5.5 ITS and GladeXML</h3><p>Glade <a title="Glade - a User Interface Builder for GTK+ and GNOME" href="#gladebib">[Glade]</a> is a user interface builder system for GTK+ and Gnome. It uses XML files (GladeXML) to store the user-interface components. The library has been ported to different platforms and offers bindings in different programming languages.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e5461" id="d4e5461"></a>Example 58: Example of a GladeXML document</div><pre>&lt;?xml version="1.0" standalone="no"?&gt;&lt;!--*- mode: xml -*--&gt;
&lt;glade-interface&gt;
 &lt;widget class="GtkWindow" id="main_window"&gt;
  &lt;property name="visible"&gt;True&lt;/property&gt;
  &lt;property name="title" translatable="yes"&gt;Glade Text Editor&lt;/property&gt;
  &lt;property name="type"&gt;GTK_WINDOW_TOPLEVEL&lt;/property&gt;
  &lt;property name="window_position"&gt;GTK_WIN_POS_NONE&lt;/property&gt;
  &lt;property name="modal"&gt;False&lt;/property&gt;
  &lt;property name="default_width"&gt;600&lt;/property&gt;
  &lt;property name="default_height"&gt;450&lt;/property&gt;
  &lt;property name="resizable"&gt;True&lt;/property&gt;
  &lt;property name="destroy_with_parent"&gt;False&lt;/property&gt;
  &lt;property name="decorated"&gt;True&lt;/property&gt;
  &lt;property name="skip_taskbar_hint"&gt;False&lt;/property&gt;
  &lt;property name="skip_pager_hint"&gt;False&lt;/property&gt;
  &lt;property name="type_hint"&gt;GDK_WINDOW_TYPE_HINT_NORMAL&lt;/property&gt;
  &lt;property name="gravity"&gt;GDK_GRAVITY_NORTH_WEST&lt;/property&gt;
  &lt;property name="focus_on_map"&gt;True&lt;/property&gt;
  &lt;property name="urgency_hint"&gt;False&lt;/property&gt;
  &lt;signal name="delete_event" handler="on_main_window_delete_event"/&gt;
  &lt;child&gt;
   &lt;widget class="GtkVBox" id="vbox1"&gt;
    &lt;property name="visible"&gt;True&lt;/property&gt;
    &lt;property name="homogeneous"&gt;False&lt;/property&gt;
    &lt;property name="spacing"&gt;0&lt;/property&gt;
    &lt;child&gt;
     &lt;widget class="GtkHandleBox" id="handlebox2"&gt;
      &lt;property name="visible"&gt;True&lt;/property&gt;
      &lt;property name="shadow_type"&gt;GTK_SHADOW_OUT&lt;/property&gt;
      &lt;property name="handle_position"&gt;GTK_POS_LEFT&lt;/property&gt;
      &lt;property name="snap_edge"&gt;GTK_POS_TOP&lt;/property&gt;
      &lt;child&gt;
       &lt;widget class="GtkMenuBar" id="menubar1"&gt;
        &lt;property name="visible"&gt;True&lt;/property&gt;
        &lt;property name="pack_direction"&gt;GTK_PACK_DIRECTION_LTR&lt;/property&gt;
        &lt;property name="child_pack_direction"&gt;GTK_PACK_DIRECTION_LTR&lt;/property&gt;
        &lt;child&gt;
         &lt;widget class="GtkMenuItem" id="File"&gt;
          &lt;property name="visible"&gt;True&lt;/property&gt;
          &lt;property name="label" translatable="yes"&gt;_File&lt;/property&gt;
          &lt;property name="use_underline"&gt;True&lt;/property&gt;
          &lt;child&gt;
           &lt;widget class="GtkMenu" id="File_menu"&gt;
            &lt;child&gt;
             &lt;widget class="GtkImageMenuItem" id="Open"&gt;
              &lt;property name="visible"&gt;True&lt;/property&gt;
              &lt;property name="label"&gt;gtk-open&lt;/property&gt;
              &lt;property name="use_stock"&gt;True&lt;/property&gt;
              &lt;signal name="activate" handler="on_Open_activate"/&gt;
             &lt;/widget&gt;
            &lt;/child&gt;
            &lt;child&gt;
             &lt;widget class="GtkImageMenuItem" id="Exit"&gt;
              &lt;property name="visible"&gt;True&lt;/property&gt;
              &lt;property name="label"&gt;gtk-quit&lt;/property&gt;
              &lt;property name="use_stock"&gt;True&lt;/property&gt;
              &lt;signal name="activate" handler="on_Exit_activate"/&gt;
             &lt;/widget&gt;
            &lt;/child&gt;
           &lt;/widget&gt;
          &lt;/child&gt;
         &lt;/widget&gt;
        &lt;/child&gt;
       &lt;/widget&gt;
      &lt;/child&gt;
     &lt;/widget&gt;
     &lt;packing&gt;
      &lt;property name="padding"&gt;0&lt;/property&gt;
      &lt;property name="expand"&gt;False&lt;/property&gt;
      &lt;property name="fill"&gt;True&lt;/property&gt;
     &lt;/packing&gt;
    &lt;/child&gt;
   &lt;/widget&gt;
  &lt;/child&gt;
 &lt;/widget&gt;
&lt;/glade-interface&gt;</pre><p>[<a href="EX-glade-its-relating-1.xml">Example's source code</a>]</p></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="its-glade" id="its-glade"></a>5.5.1 Integration of ITS into GladeXML</h4><p>The content of the GladeXML files are mostly composed of data that should not be translated: user-interface widgets properties. Text content is limited to titles, labels and a few various other types of strings.</p><p>GladeXML does offer support for some of the ITS features, but not all of them. While it would be technically feasible to allow the use of additional ITS markup directly in your GladeXML resources, there is little point doing it here because these resources are closely tied to the Glade's editors and compilers which would have to be modified as well.</p></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="glade-its-relating" id="glade-its-relating"></a>5.5.2 Associating Existing GladeXML Markup with ITS</h4><p>GladeXML offers a <code>translatable</code> attribute that provides the same functionality as <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code>. The <code>comments</code> attribute can also be associated with localization notes.</p><p>Like for other formats, existing features of GladeXML can be associated with ITS data categories using global rules, so ITS-enabled tools can seamlessly process  GladeXML source documents.</p><div class="exampleOuter"><div class="exampleHeader"><a name="d4e5495" id="d4e5495"></a>Example 59: Associating GladeXML markup with ITS</div><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"&gt;
 &lt;!-- ITS rules for Glade 2.0, based on http://glade.gnome.org/glade-2.0.dtd --&gt;
 &lt;its:translateRule selector="/glade-interface" translate="no"/&gt;
 &lt;its:translateRule selector="//*[@translatable='yes']" translate="yes"/&gt;
 &lt;its:translateRule selector="//atkaction/@description" translate="yes"/&gt;
 &lt;its:locNoteRule selector="//*[@translatable='yes']"
  locNoteType="description" locNotePointer="@comments"/&gt;
&lt;/its:rules&gt;</pre><p>[<a href="EX-glade-its-relating-2.xml">Example's source code</a>]</p></div></div></div><div class="div2">
<h3><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="docbook" id="docbook"></a>5.6 ITS and DocBook</h3><p>DocBook is a general purpose XML schema particularly well suited to
books and papers about computer hardware and software (though it is by
no means limited to these applications). DocBook is maintained by the
<a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">DocBook
Technical Committee</a> of <a href="http://www.oasis-open.org/">OASIS</a>.</p><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="docbook-plus-its" id="docbook-plus-its"></a>5.6.1 Integration of ITS into DocBook</h4><p>DocBook V5.0 schema is maintained as a very modular and easy to
customize schema written in RELAX NG <a title="Information&#xA; technology – Document Schema Definition Language (DSDL) – Part 2:&#xA; Regular-grammar-based validation – RELAX NG." href="#relaxng">[RELAX NG 1.0]</a>. General
techniques for schema customization are described in <a title="DocBook V5.0: The Transition&#xA; Guide" href="#docbook-howto">[DocBook V5.0 HOWTO]</a>.</p><p>The ITS additions involve the following changes to the DocBook schema:</p><ol class="depth1"><li><p>Adding the ITS <a href="http://www.w3.org/TR/2007/REC-its-20070403/#span.attributes">local
attributes</a> to every existing DocBook element.</p><p>Not all ITS
local attributes are added to the schema, as DocBook already provides its
own means for specifying directionality of text. Such existing markup
should be associated with ITS data categories using <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code>
element. See <a class="section-ref" href="#relating-docbook-plus-its">Section 5.6.2: Associating existing DocBook markup with ITS</a>.</p></li><li><p>Allowing the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element inside
DocBook <code>info</code> element which is a general metadata container.</p></li><li><p>Allowing the <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code> as inline element almost everywhere where plain text could be.</p></li></ol><div class="exampleOuter"><div class="exampleHeader"><a name="EX-docbook-plus-its" id="EX-docbook-plus-its"></a>Example 60: DocBook schema customization</div><pre># This schema integrates ITS markup (http://www.w3.org/TR/its/) 
# into DocBook schema (http://docbook.org)
#
# This schema conforms to Conformance Type 1 defined in
# http://www.w3.org/TR/its/#conformance-product-schema
# 
# Schema adds the following ITS elements into DocBook schema: 
#  * rules
#  * ruby
#
# Schema adds the following local ITS attributes into DocBook schema:
#  * translate
#  * locNote
#  * locNoteType
#  * locNoteRef
#  * term
#  * termInfoRef

# Namespace declarations for DocBook, ITS and HTML
# (HTML is used internally in DocBook schema)  
namespace db = "http://docbook.org/ns/docbook"
namespace its = "http://www.w3.org/2005/11/its"
namespace html = "http://www.w3.org/1999/xhtml"

# Include base DocBook schema
include "docbook.rnc"
{
   # Exclude ITS markup from "wildcard" element
   db._any =
      element * - (db:* | html:* | its:*) {
         (attribute * { text }
          | text
          | db._any)*
      }
}

# Include base ITS schema
include "its.rnc"

# Define pattern for local ITS attributes
db.its.attributes = 
   its-att.translate.attributes?
   &amp; its-att.locNote.attributes?
   &amp; its-att.term.attributes?
   &amp; its-att.version.attributes?

# Add local ITS attributes to all DocBook elements
db.common.base.attributes &amp;= db.its.attributes

# Allow its:rules inside info element
db.info.extension |= its-rules

# Allow Ruby markup almost everywhere
db.ubiq.inlines |= its-ruby
</pre><p>[<a href="docbook/docbook-its.rnc">Example's source code</a>]</p></div><p>For your convenience there is also available a  “flattened” schema
stored inside one file.</p><ul><li><p><a href="docbook/dbits.rnc">dbits.rnc</a> (RELAX NG compact syntax schema in one file)</p></li><li><p><a href="docbook/dbits.rng">dbits.rng</a> (RELAX NG schema in one file)</p></li></ul><p>There is no need to add the  <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#span">its:span</a></code> element as
DocBook provides similar element called <code>phrase</code> which can be
used for attaching ITS local attributes to an arbitrary piece of
text.</p><p>The following example shows a sample DocBook article conforming to
the DocBook+ITS schema. The <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#translateRule">its:translateRule</a></code> element is used to indicate that
function names (marked up using the  <code>function</code> element) should not be
translated. The first paragraph is also marked as not to be translated
using local ITS markup.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-docbook-plus-its-1" id="EX-docbook-plus-its-1"></a>Example 61: Sample DocBook document with ITS markup</div><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;article xmlns="http://docbook.org/ns/docbook" 
         xmlns:its="http://www.w3.org/2005/11/its" 
         xmlns:db="http://docbook.org/ns/docbook" 
         version="5.0" xml:lang="en"&gt;
  &lt;info&gt;
    &lt;title&gt;Sample article&lt;/title&gt;
    &lt;its:rules version="1.0"&gt;
      &lt;its:translateRule translate="no" selector="//db:function"/&gt;
    &lt;/its:rules&gt;
  &lt;/info&gt;
  &lt;para its:translate="no"&gt;Non-translatable content&lt;/para&gt;
  &lt;section&gt;
    &lt;title&gt;Sample section&lt;/title&gt;
    &lt;para&gt;You can delete file using &lt;function&gt;unlink()&lt;/function&gt;
     function.&lt;/para&gt;
  &lt;/section&gt;
&lt;/article&gt;</pre><p>[<a href="docbook/ex-docbook-plus-its-1.xml">Example's source code</a>]</p></div><div class="div4">
<h5><a name="docbook-plus-its-cs" id="docbook-plus-its-cs"></a>5.6.1.1Conformance statement</h5><p>This schema conforms to <a href="http://www.w3.org/TR/2007/REC-its-20070403/#conformance-product-schema">Conformance
Type 1</a> of the ITS specification.</p><p>The schema adds the following ITS elements to the  DocBook schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#ruby">its:ruby</a></code></p></li></ul><p>The schema adds the following local ITS attributes to the  DocBook schema:</p><ul><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.translate">its:translate</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNote">its:locNote</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteType">its:locNoteType</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.locNoteRef">its:locNoteRef</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.term">its:term</a></code></p></li><li><p><code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#att.local.with-ns.attribute.termInfoRef">its:termInfoRef</a></code></p></li></ul></div></div><div class="div3">
<h4><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="relating-docbook-plus-its" id="relating-docbook-plus-its"></a>5.6.2 Associating existing DocBook markup with ITS</h4><p>A number of DocBook constructs implement the same semantics as some
of the ITS data categories. In addition, some of the DocBook
attributes have values which should be translated, which is not the default for XML
documents according to the <a href="http://www.w3.org/TR/2007/REC-its-20070403/#datacategories-defaults-etc">ITS default
settings</a>. These attributes need to be
identified as needing translation.</p><div class="note"><p><span class="note-head">Note: </span>When you have the choice of using a DocBook construct or an ITS
construct to express the same thing, make sure you use the DocBook
construct to ensure DocBook processing tools work properly. Use ITS local
markup only if DocBook does not provide an equivalent.</p></div><p>An external ITS <code><a href="http://www.w3.org/TR/2007/REC-its-20070403/#rules">its:rules</a></code> element can
summarize these relationships. Because DocBook use is widespread and
diverse, the rules defined here are just examples which may need further
tailoring for specific use.</p><div class="exampleOuter"><div class="exampleHeader"><a name="EX-relating-docbook-plus-its-1" id="EX-relating-docbook-plus-its-1"></a>Example 62: ITS external rules for DocBook documents</div><pre>&lt;its:rules xmlns:its="http://www.w3.org/2005/11/its" 
	   xmlns:db="http://docbook.org/ns/docbook"
	   xmlns:xlink="http://www.w3.org/1999/xlink"
	   version="1.0"&gt;

 &lt;!-- Translatable attributes --&gt;
 &lt;its:translateRule selector="//db:table/@summary" translate="yes"/&gt;
 &lt;its:translateRule selector="//db:*/@xlink:title" translate="yes"/&gt;
 &lt;its:translateRule selector="//db:*/@xreflabel" translate="yes"/&gt;
 &lt;its:translateRule selector="//db:*/@label" translate="yes"/&gt;

 &lt;!-- Non-translatable elements/attributes --&gt;
 &lt;its:translateRule translate="no" selector="//db:*[@revisionflag = 'deleted']"/&gt;
 &lt;its:translateRule translate="no" selector="//db:*[@revisionflag = 'deleted']//@*"/&gt;
 &lt;its:translateRule translate="no"
		    selector="//db:acronym
			      | //db:author 
			      | //db:classname 
			      | //db:command 
			      | //db:constant 
			      | //db:date
			      | //db:editor 
			      | //db:email 
			      | //db:envar 
			      | //db:errorcode 
			      | //db:exceptionname 
			      | //db:filename 
			      | //db:function 
			      | //db:initializer 
			      | //db:interfacename 
			      | //db:markup 
			      | //db:methodname 
			      | //db:modifier 
			      | //db:ooclass 
			      | //db:ooexception 
			      | //db:oointerface 
			      | //db:option 
			      | //db:parameter 
			      | //db:person 
			      | //db:personname 
			      | //db:productnumber 
			      | //db:property
			      | //db:returnvalue 
			      | //db:symbol 
			      | //db:tag 
			      | //db:type 
			      | //db:uri 
			      | //db:varname"/&gt;

 &lt;!-- Possible terms --&gt;
 &lt;its:termRule selector="//db:glossterm" term="yes"/&gt;
 &lt;its:termRule selector="//db:firstterm" term="yes"/&gt;
 &lt;its:termRule selector="//db:abbrev"    term="yes"/&gt;
 &lt;its:termRule selector="//db:acronym"   term="yes"/&gt;

 &lt;!-- Bidirectional information --&gt;
 &lt;its:dirRule selector="//db:*[@dir='ltr']" dir="ltr"/&gt;
 &lt;its:dirRule selector="//db:*[@dir='rtl']" dir="rtl"/&gt;
 &lt;its:dirRule selector="//db:*[@dir='lro']" dir="lro"/&gt;
 &lt;its:dirRule selector="//db:*[@dir='rlo']" dir="rlo"/&gt;

 &lt;!-- Elements within text --&gt;
 &lt;its:withinTextRule withinText="yes"
		     selector="//db:abbrev 
			       | //db:accel 
			       | //db:acronym 
			       | //db:application 
			       | //db:author 
			       | //db:citation  
			       | //db:citebiblioid 
			       | //db:citerefentry 
			       | //db:citetitle 
			       | //db:classname 
			       | //db:code 
			       | //db:command 
			       | //db:computeroutput 
			       | //db:constant 
			       | //db:database 
			       | //db:date 
			       | //db:editor 
			       | //db:email 
			       | //db:emphasis 
			       | //db:envar 
			       | //db:errorcode 
			       | //db:errorname 
			       | //db:errortext 
			       | //db:errortype 
			       | //db:exceptionname 
			       | //db:filename 
			       | //db:foreignphrase 
			       | //db:function 
			       | //db:guibutton 
			       | //db:guiicon 
			       | //db:guilabel 
			       | //db:guimenu 
			       | //db:guimenuitem 
			       | //db:guisubmenu 
			       | //db:hardware 
			       | //db:initializer 
			       | //db:interfacename 
			       | //db:jobtitle 
			       | //db:keycap 
			       | //db:keycode 
			       | //db:keycombo 
			       | //db:keysym 
			       | //db:link 
			       | //db:literal 
			       | //db:markup 
			       | //db:menuchoice 
			       | //db:methodname 
			       | //db:modifier 
			       | //db:mousebutton 
			       | //db:olink
			       | //db:ooclass 
			       | //db:ooexception 
			       | //db:oointerface 
			       | //db:option 
			       | //db:optional 
			       | //db:org 
			       | //db:orgname 
			       | //db:package 
			       | //db:parameter 
			       | //db:person 
			       | //db:personname 
			       | //db:phrase 
			       | //db:productname 
			       | //db:productnumber 
			       | //db:prompt 
			       | //db:property
			       | //db:quote 
			       | //db:replaceable 
			       | //db:returnvalue 
			       | //db:shortcut 
			       | //db:subscript 
			       | //db:superscript 
			       | //db:symbol 
			       | //db:systemitem 
			       | //db:tag 
			       | //db:token 
			       | //db:trademark 
			       | //db:type 
			       | //db:uri 
			       | //db:userinput
			       | //db:varname 
			       | //db:wordasword"/&gt;

 &lt;its:withinTextRule withinText="nested"
		     selector="//db:alt 
			       | //db:footnote 
			       | //db:remark 
			       | //db:indexterm 
			       | //db:primary 
			       | //db:secondary 
			       | //db:tertiary"/&gt;

&lt;/its:rules&gt;</pre><p>[<a href="docbook/ex-relating-docbook-plus-its-1.xml">Example's source code</a>]</p></div></div></div></div></div><div class="back"><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="d4e5690" id="d4e5690"></a>A References (Non-Normative)</h2><dl><dt class="label"><a name="langtag" id="langtag"/>BCP 47</dt><dd>Addison Phillips and Mark Davis, editors. <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt"><cite>Tags for Identifying Languages</cite></a>. Best Current Practice 47 September 2006. Available at <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">http://www.rfc-editor.org/rfc/bcp/bcp47.txt</a></dd><dt class="label"><a name="bidixhtmlbp" id="bidixhtmlbp"/>Bidi in X/HTML</dt><dd>Richard Ishida, editor. <a href="http://www.w3.org/TR/2007/WD-i18n-html-tech-bidi-20070606/"><cite>Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content</cite></a>. W3C Working Draft 6 June 2007. Available at <a href="http://www.w3.org/TR/2007/WD-i18n-html-tech-bidi-20070606/">http://www.w3.org/TR/2007/WD-i18n-html-tech-bidi-20070606/</a>. The latest version of <a href="http://www.w3.org/TR/i18n-html-tech-bidi/">Bidi in X/HTML</a> is available at http://www.w3.org/TR/i18n-html-tech-bidi/ .</dd><dt class="label"><a name="charmod" id="charmod"/>CharMod</dt><dd>Martin J. Dürst, François Yergeau, Richard Ishida, Misha Wolf, Tex Texin, editors. <a href="http://www.w3.org/TR/2005/REC-charmod-20050215/"><cite>Character Model for the World Wide Web 1.0: Fundamentals</cite></a>. W3C Recommendation 15 February 2005. Available at <a href="http://www.w3.org/TR/2005/REC-charmod-20050215/">http://www.w3.org/TR/2005/REC-charmod-20050215/</a>. The latest version of <a href="http://www.w3.org/TR/charmod/">CharMod</a> is available at http://www.w3.org/TR/charmod/ .</dd><dt class="label"><a name="dita10" id="dita10"/>DITA 1.0</dt><dd>Michael Priestley, JoAnn Hackos, et. al., editors. <a href="http://www.oasis-open.org/committees/download.php/15316/dita10.zip"><cite>OASIS Darwin Information Typing
Architecture (DITA) Language Specification v1.0</cite></a>. OASIS Standard 9 May 2005. Available at <a href="http://www.oasis-open.org/committees/download.php/15316/dita10.zip">http://www.oasis-open.org/committees/download.php/15316/dita10.zip</a>.</dd><dt class="label"><a name="docbook-howto" id="docbook-howto"/>DocBook V5.0 HOWTO</dt><dd>Jirka Kosek, Norman
 Walsh and Dick Hamilton. <a href="http://docbook.org/docs/howto/"><cite>DocBook V5.0: The Transition
 Guide</cite></a>. Available at <a href="http://docbook.org/docs/howto/">http://docbook.org/docs/howto/</a>.</dd><dt class="label"><a name="gladebib" id="gladebib"/>Glade</dt><dd><a href="http://glade.gnome.org/"><cite>Glade - a User Interface Builder for GTK+ and GNOME</cite></a>. The GNOME Foundation. Available at <a href="http://glade.gnome.org/">http://glade.gnome.org/</a>.</dd><dt class="label"><a name="itsspec" id="itsspec"/>ITS</dt><dd>Christian Lieske and Felix Sasaki, editors. <a href="http://www.w3.org/TR/2007/REC-its-20070403/"><cite>Internationalization Tag Set (ITS) Version 1.0</cite></a>. W3C Recommendation 3 April 2007. Available at <a href="http://www.w3.org/TR/2007/REC-its-20070403/">http://www.w3.org/TR/2007/REC-its-20070403/</a>. The latest version of <a href="http://www.w3.org/TR/its/">ITS</a> is available at http://www.w3.org/TR/its/ .</dd><dt class="label"><a name="itsreq" id="itsreq"/>ITS REQ</dt><dd>Yves Savourel, editor. <a href="http://www.w3.org/TR/2006/WD-itsreq-20060518/"><cite>Internationalization and Localization Markup Requirements</cite></a>. W3C Working Draft 18 May 2006. Available at <a href="http://www.w3.org/TR/2006/WD-itsreq-20060518/">http://www.w3.org/TR/2006/WD-itsreq-20060518/</a>. The latest version of <a href="http://www.w3.org/TR/itsreq/">ITS REQ</a> is available at http://www.w3.org/TR/itsreq/ .</dd><dt class="label"><a name="nvdl" id="nvdl"/>NVDL</dt><dd><cite>Information technology -- Document Schema Definition Languages (DSDL) -- Part 4: Namespace-based Validation Dispatching Language (NVDL).</cite> International Organization for Standardization (ISO) ISO/IEC 19757-4:2003.</dd><dt class="label"><a name="relaxng" id="relaxng"/>RELAX NG 1.0</dt><dd><cite>Information
 technology – Document Schema Definition Language (DSDL) – Part 2:
 Regular-grammar-based validation – RELAX NG.</cite>,
 International Organization for Standardization (ISO) ISO/IEC
 19757-2:2003.</dd><dt class="label"><a name="rubyan" id="rubyan"/>Ruby Annotation</dt><dd>Marcin Sawicki, Michel Suignard, Masayasu Ishikawa, et al. editors. <a href="http://www.w3.org/TR/2001/REC-ruby-20010531/"><cite>Ruby Annotation</cite></a>. W3C Recommendation 31 May 2001 Available at <a href="http://www.w3.org/TR/2001/REC-ruby-20010531/">http://www.w3.org/TR/2001/REC-ruby-20010531/</a>. The latest version of <a href="http://www.w3.org/TR/ruby/">Ruby Annotation</a> is available at http://www.w3.org/TR/ruby/ .</dd><dt class="label"><a name="tei" id="tei"/>TEI</dt><dd>Lou Burnard and Syd Bauman, editors. <a href="http://www.tei-c.org/P5/"><cite>Text Encoding Initiative Guidelines development version (P5)</cite></a>. TEI Consortium, Charlottesville, Virginia, USA, Text Encoding Initiative.</dd><dt class="label"><a name="utr20" id="utr20"/>Unicode in XML</dt><dd>Martin Dürst and  Asmus Freytag. <a href="http://www.w3.org/TR/unicode-xml/"><cite>Unicode in XML and other Markup Languages</cite></a>. W3C Working Group Note 16 May 2007, Unicode Technical report #20. The latest version of <a href="http://www.w3.org/TR/unicode-xml">Unicode in XML</a> is available at http://www.w3.org/TR/unicode-xml/ .</dd><dt class="label"><a name="xhtml10" id="xhtml10"/>XHTML 1.0</dt><dd>Steven Pemperton et al., editors. <a href="http://www.w3.org/TR/2002/REC-xhtml1-20020801/"><cite>XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition)</cite></a>. W3C Recommendation 26 January 2000, revised 1 August 2002. Available at <a href="http://www.w3.org/TR/2002/REC-xhtml1-20020801/">http://www.w3.org/TR/2002/REC-xhtml1-20020801/</a>. The latest version of <a href="http://www.w3.org/TR/xhtml1/">XHTML 1.0</a> is available at http://www.w3.org/TR/xhtml1/ .</dd><dt class="label"><a name="xhtmlmod" id="xhtmlmod"/>XHTMLMod1.1</dt><dd>Daniel Austin et al., editors. <a href="http://www.w3.org/TR/2006/WD-xhtml-modularization-20060705/"><cite>XHTML™ Modularization 1.1</cite></a>. W3C Working Draft 5 July 2006. Available at <a href="http://www.w3.org/TR/2006/WD-xhtml-modularization-20060705/">http://www.w3.org/TR/2006/WD-xhtml-modularization-20060705/</a>. The latest version of <a href="http://www.w3.org/TR/xhtml-modularization/">XHTMLMod1.1</a> is available at http://www.w3.org/TR/xhtml-modularization/ .</dd><dt class="label"><a name="xinclude" id="xinclude"/>XInclude 1.0</dt><dd>Jonathan Marsh, David Orchard and Daniel Veillard, editors.
- <a href="http://www.w3.org/TR/2006/REC-xinclude-20061115/"><cite>XML Inclusions (XInclude) Version 1.0 (Second Edition)</cite></a>. W3C Recommendation 15 November 2006. Available at <a href="http://www.w3.org/TR/2006/REC-xinclude-20061115/">http://www.w3.org/TR/2006/REC-xinclude-20061115/</a>. The latest version of <a href="http://www.w3.org/TR/xinclude/">XInclude 1.0</a> is available at http://www.w3.org/TR/xinclude/ .</dd><dt class="label"><a name="xliff12" id="xliff12"/>XLIFF 1.2</dt><dd>Yves Savourel et al., editors. <a href="http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html"><cite>XLIFF Version 1.2</cite></a>. OASIS Committee Specification 24 July 2007. Available at <a href="http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html">http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html</a>. The latest version of <a href="http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html"><cite>XLIFF 1.2</cite></a> is available at http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html .</dd><dt class="label"><a name="xlink1" id="xlink1"/>XLink 1.0</dt><dd>Steve DeRose, Eve Maler and David Orchard, editors. 
- <a href="http://www.w3.org/TR/2001/REC-xlink-20010627/"><cite>XML Linking Language 1.0</cite></a>. W3C Recommendation 27 June 2001. Available at <a href="http://www.w3.org/TR/2001/REC-xlink-20010627/">http://www.w3.org/TR/2001/REC-xlink-20010627/</a>. The latest version of <a href="http://www.w3.org/TR/xlink/">XLink 1.0</a> is available at http://www.w3.org/TR/xlink/ .</dd><dt class="label"><a name="xmlid" id="xmlid"/>xml:id</dt><dd>Jonathan Marsh, Daniel Veillard and Norman Walsh, editors.
- <a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/"><cite>xml:id Version 1.0</cite></a>. W3C Recommendation 9 September 2005. Available at <a href="http://www.w3.org/TR/2005/REC-xml-id-20050909/">http://www.w3.org/TR/2005/REC-xml-id-20050909/</a>. The latest version of <a href="http://www.w3.org/TR/xml-id/">xml:id</a> is available at http://www.w3.org/TR/xml-id/ .</dd><dt class="label"><a name="xmlns" id="xmlns"/>XML Names</dt><dd>Tim Bray, Dave Hollander and Andrew Layman, editors. <a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/"><cite>Namespaces in XML</cite></a>. W3C Recommendation 14 January 1999. Available at <a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/">http://www.w3.org/TR/1999/REC-xml-names-19990114/</a>. The latest version of <a href="http://www.w3.org/TR/REC-xml-names/">XML Names</a> is available at http://www.w3.org/TR/REC-xml-names/ .</dd><dt class="label"><a name="xmlspecbib" id="xmlspecbib"/>XML Spec</dt><dd><a href="http://www.w3.org/2002/xmlspec/"><cite>The XML Spec Schema and Stylesheets</cite></a>. Available at http://www.w3.org/2002/xmlspec/ .</dd></dl></div><div class="div1">
<h2><a href="#contents"><img src="images/topOfPage.gif" align="right" height="26" width="26" title="Go to the table of contents." alt="Go to the table of contents."/></a><a name="Acknowledgements" id="Acknowledgements"></a>B Acknowledgements (Non-Normative)</h2><p>This document has been developed with important contributions from past and present member of the Working Group: Bartosz Bogacki (W3C Invited Expert), Martin Dürst (W3C Invited Expert), Tim Foster, Richard Ishida (W3C/ERCIM), Masaki Itagaki, Jirka Kosek (W3C Invited Expert), Christian Lieske (SAP AG), Sebastian Rahtz (W3C Invited Expert), Felix Sasaki (W3C/Keio), Yves Savourel (ENLASO Corporation), Diane Stoick (The Boeing Company), Najib Tounsi (Ecole Mohammadia d'Ingenieurs Rabat (EMI)), and Andrzej Zydron.</p><p>At the date of publication, the members of the Working Group were: Bartosz Bogacki (W3C Invited Expert), Damien Donlon (Sun Microsystems, Inc.), Martin Dürst (W3C Invited Expert), Poonam Gupta (Centre for Development of Advanced Computing (CDAC)), Richard Ishida (W3C/ERCIM), Jirka Kosek (W3C Invited Expert), Christian Lieske (SAP AG), Sebastian Rahtz (W3C Invited Expert), Francois Richard (HP), Goutam Saha (Centre for Development of Advanced Computing (CDAC)), Felix Sasaki (W3C/Keio), Yves Savourel (ENLASO Corporation), Diane Stoick (The Boeing Company), and Najib Tounsi (Ecole Mohammadia d'Ingenieurs Rabat (EMI)).</p></div></div></body></html>