HP 9000 Computers Native Language Support: User's Guide Native Language Support: User's Guide HP 9000 Computers Fli..- HEWLETT a:~ PACKARD HP Part No. 82355-90036 Printed in USA August 1992 Third Edition E0892 Legal Notices The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material. Copyright © 1983-92 Hewlett-Packard Company Reproduction, adaptation, or translation without prior written permission is prohibited, except as allowed under the copyright laws. Restricted Rights Legend .. Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in sub-paragraph (c)(l)(ii) of the Rights in Technical Data and Computer Software clause in DFARS 252.227-7013. Hewlett-Packard Company 3000 Hanover Street Palo Alto, CA 94304 U.S.A. Rights for non-DOD U.S. Government Departments and Agencies are as set forth in FAR 52.227-19(c)(1,2). Use of this manual and flexible disk(s) or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited. All rights reserved. Copyright © 1980, 1984, 1986 UNIX System Laboratories, Inc. UNIX® is a registered trademark of UNIX System Laboratories, Inc. in the USA and other countries. Printing History New editions of this manual will incorporate all material updated since the previous edition. The manual printing date and part number indicate its current edition. The printing date changes when a new edition is printed. (Minor corrections and updates which are incorporated at reprint do not cause the date to change.) The manual part number changes when extensive technical changes are incorporated. May 1990. First Edition January 1991. Second Edition • This edition updates the previous document called Native Language Support Concepts and Tutorials. This edition includes corrections and additions for the HP-UX 8.0 release. Major changes and additions include: An overview of Native Language Support; improved organization to improve access to information in a more logical sequence; addition of information on supported codesets; expanded information on localizing international software; added illustrations to simplify complex topics; and added depth and coverage on may topics. August 1992. Third Edition • This edition documents the addition to NLS of World Portability Interface (WPI), and its wide-character encoding. This is a standardized approach (XPG4) and is the preferred approach. iii Contents 1. Overview UNIX Background .... 1-1 The NLS Concept .... 1-1 The NLS Conceptual Model 1-2 U sing this Manual .... 1-4 Typographical Conventions in This Manual 1-7 Related HP-UX Manuals. 1-8 2. Introduction to NLS Overview of Software Internationalization . 2-1 Components of Internationalizing and Localizing with NLS . 2-3 Internationalization . 2-3 Localization . 2-3 . Aspects of NLS Support . 2-4 Character and Text Handling . 2-4 Data Integrity . 2-4 Character Sets and Encoding 2-4 Character Type and Conversion 2-6 Local Customs and Conventions 2-6 Numeric Formatting. 2-6 Monetary Formatting . 2-7 Display of Time ...... 2-7 Display of Days, Weeks, Months 2-8 Collation. 2-8 Messages ........... 2-9 Language Variations. 2-10 Comparing Strings and Comparing Characters 2-10 Regular Expressions . 2-12 Contents-1 3. Using International Software NLS Environmental Variables 3-1 Default Values . 3-3 Setting your Environment . .. 3-4 Setting Your Terminal . 3-5 Reference Information for Internationalized Commands 3-5 Internationalized Messages . 3-6 U sing Internationalized Commands . 3-6 4. Administering International Software Finding NLS Files ..... 4-2 The Default User Environment 4-3 Installing Message Catalogs 4-3 Installing Optional Locales . 4-4 Peripheral Configuration . 4-4 5. Localizing International Software Localizing the User Environment 5-2 Localizing Message Catalogs 5-2 The C Locale Messages 5-3 Translating Messages 5-3 Translation Problems . 5-4 Installing Localized Messages 5-4 Creating a Locale . 5-5 Script Requirements for localedef 5-7 localedef Syntax ...... 5-8 LC_ALL Subcategories 5-10 LC_COLLATE Subcategories 5-11 Single-Character Element 5-12 Multi-character Element . 5-12 Ellipsis Symbol . 5-13 UNDEFINED Symbol . 5-13 LC_CTYPE Subcategories . 5-15 LC_MESSAGES Subcategories 5-20 LC_MONETARY Subcategories 5-21 LC_NUMERIC Subcategories 5-24 LC_TIME Subcategories . 5-25 Installing a Language Definition Table . 5-27 Contents-2 6. Developing International Software General Programming Issues . 6-1 Aspects of International Program Design . 6-2 Other Aspects . 6-4 Initializing NLS. 6-6 Setting Program Locale . 6-6 Retrieving Locale Information 6-8 Accessing Language Tables . 6-8 Programming with the Worldwide Portability Interface 6-12 WPI Interfaces . 6-12 Character and String Processing . 6-13 Character Handling . 6-13 Upshifting and Downshifting Characters . 6-14 Identifying Character Traits 6-15 Numeric Formatting. 6-16 Date and Time ........... 6-16 Input and Output in Internationalized Programs 6-17 Printing Formatted Output 6-17 Reading Formatting Input . 6-17 U sing Flexible Formatting . 6-18 Example program using wide characters. 6-20 Conversion of Existing Programs 6-21 N on-WPI Interfaces . 6-22 Character and String Processing 6-22 Character Handling . 6-22 Upshifting and Downshifting Characters 6-22 Identifying Character Traits 6-24 Numeric Formatting . 6-25 Date and Time . 6-26 Monetary Formatting 6-26 String Comparisons . 6-28 Guidelines for Creating Internationalized Programs 6-29 Contents-3 7. The Message Catalog System Creating and Using a Message Catalog System 7-2 Programming for Messages . 7-3 Opening a Message Catalog with catopen 7-3 Recommended Initialization 7-4 Search Path and Naming Conventions 7-6 Retrieving Messages . 7-7 Closing a Message Catalog 7-8 Default Messages 7-8 Compiling and Linking 7-9 Creating aNew Message Catalog 7-9 The Message Text Source File 7-9 Compiling a Message Catalog . 7-11 An Example of Programming with Message Catalogs 7-11 Special Considerations for Messaging 7-12 Libraries with Messages 7-15 Conversion of Existing Programs for NLS Messaging 7-16 Step 1. Finding Strings in a Program 7-17 Step 2. Removing Non-Messages from the Strings. 7-18 Step 3. Inserting catgets Calls 7-18 Step 4. Editing the Modified Source Program 7-20 Step 5. Editing the Message Text Source File. 7-20 Step 6. Creating a Message Catalog . 7-20 Testing a Message Catalog 7-21 Installing a Message Catalog 7-22 Source Code Management 7-22 Keeping nl_prog.c Files 7-22 Multi- file Programs 7-22 Adding a Message to a Messaging Program . 7-23 Using "make" Files 7-24 Guidelines for Using Messaging 7-25 Contents-4 8. Advanced NLS Topics Codeset Conversion . 8-1 The Character Conversion Command-iconv(l) . 8-2 Conversion Routines-iconv(3C) 8-2 Processing Right-to-Left Languages . 8-6 . Locale Information 8-8 Initialization . 8-10 Special Locales . 8-10 Special Message Catalogs 8-10 Default Message Catalogs 8-11 Programs That Call exec . 8-11 Messaging: printf/scanf Data Formatting 8-12 A. Special Topics for HP's 16-bit Interfaces Aspects of Program Design .. A-2 Code Sets ............ A-3 Data Integrity . A-5 Programming with Multi-byte Characters A-5 Version # 1 (Single-Byte Codesets) A-6 Version #2 (Code Set Independent) . A-8 Conversion of Existing Programs . A-9 Guidelines for Processing Multi-byte Data A-I0 B. Example of Internationalized Software Example Program Using NLS Routines - rtlcat B-1 Include Files: . B-2 External Declarations: . B-2 Forward References: .. B-3 General Constants: . B-3 Limits: ..... B-3 Right-to-Left Terminal Constants: . B-3 Error Message Numbers: B-3 Error Message Strings: . B-4 Types: ..... B-4 Global Variables: B-4 Main Program: .. B-4 Makefile Example .. B-15 Contents-5 C. NLS References D. Previous Usage Obsolete Routines. D-2 Proprietary Commands and Interfaces . D-5 E. Languages and Codesets Displaying Character Sets on Your Terminal E-5 F. LC_COLLATE Example for Spanish Glossary Index Contents-6 Figures 1-1. NLS Conceptual Model . 1-3 6-1. Retrieving the User's Environment 6-5 6-2. The Program Environment . 6-8 7-1. The Message Catalog System . 7-5 7-2. Naming and Locating Message Catalogs 7-6 7-3. Using gencat 0 to Generate Message Catalog 7-9 7-4. Converting a Non-Internationalized Program . 7-16 7-5. Using findstr to Locate String Constants . 7-17 7-6. Using the insertmsg Command 7-19 E-1. Roman8 Coded Character Set ..... E-4 Contents-7 Tables 1-1. Finding Information in the NLS User's Guide .. 1-5 2-1. Sorting Example: C vs. German 2-10 2-2. Sorting Example: C vs. Spanish 2-11 2-3. Sorting Example: C vs German . 2-11 3-1. NLS Environment Variables 3-2 4-1. NLS Directories and Files . 4-2 5-1. Primary Subdivisions of a Language Table 5-7 5-2. Header Keywords . ... 5-8 5-3. LC_ALL Subcategories 5-10 5-4. LC_COLLATE Subcategories 5-11 5-5. LC_CTYPE Categories . 5-15 5-6. LC_MESSAGES Subcategories . 5-20 5-7. LC_MONETARY Subcategories 5-21 5-8. LC_NUMERIC Keywords . 5-24 5-9. LC_ TIME Subcategories . 5-25 6-1. A Comparison of a "Standard" Application with its NLS Version . .. 6-3 6-2. Categories for setlocale ....