This chapter provides an overview of the process required to produce localized books for Silicon Graphics as well as specific notes that may be useful to you. The following topics are discussed:
Silicon Graphics' Localization Department (L10N) oversees the language translation of IRIX operating systems, software, and books. As the project manager for localizing books, L10N determines the books to be translated, qualifies and hires the localization vendors, details the project schedule, provides linguistic review at various stages of the project, and authorizes the payment of your bills.
Technical Publications Production provides production personnel to prepare files, complete localization specs, provide technical support, perform quality assurance and help testing, generate test reports, file bug reports, and build final images for manufacturing release.
In general, all book localization projects include the same series of tasks and follow a schedule based on dependencies.
Table 1-1 shows a typical localization project's milestones, the expected duration to complete the task, and the milestone(s) that must be completed before the task can begin.
Table 1-1. Book Localization Milestones, Duration, and Dependencies
The schedule for a typical localization project, including the project's milestones and dependencies, is shown in Figure 1-1.
Before the project starts, you will be given some hardware and the software tools you need to meet your deliverables requirement.
The L10N vendor kit includes
ftp instructions (or see Chapter 10, “Transferring Files Using FTP”)
Technical Publications Production will supply the following:
Silicon Graphics' WorldView Books Production Guide
IRIS InSight Professional Publisher Templates (also known as IPTemplates)
Book building tools and instructions for installation
make
insight_dev
prod_toolroot
impr_rip
impr_kanji (Japanese only)
Scripts and instructions for their use
gethelp (see “Helpmaps”)
installtestbooks (“Installing a Localized Book for Testing”)
Silicon Graphics system (if necessary)
Silicon Graphics will supply all the files you need to produce the English version of a book. These files and their naming conventions are discussed in these sections:
You will receive a localization specification for each book undergoing localization. The localization specification provides a list of the files that are being supplied to you and describes the deliverables expected from you.
Word count text files are ASCII text files containing all word count information for a new English book. If a book is being revised, the word count file will also show the differences in word counts from a prior English revision that was later localized to the current English revision.
The naming convention is YY.MM.DD.00X-XXXX-nnn.wc.txt for books undergoing localization for the first time and YY.MM.DD.00X-XXXX-nnX_nnY, where 00X_00Y are the two revisions that have been compared to one another.
Example 1-1 shows a typical wc.txt file.
007-1342-090 |
|
|
|
007-1342-070 |
|
|
|
File Names | Total word count | Inserted | Deleted |
*.doc | 3442 | 1343 | 275 |
Totals | 3442 | 1343 | 275 |
Total diffs = | 1618 |
|
|
The files you download from Silicon Graphics should be all that you need to produce an English version of a document. These files include
| *.doc | FrameMaker source files for the book | |
| bookfile | FrameMaker bookfile | |
| *.sgm | SGML files for the online version of the book | |
| Makefile | Text file with instructions | |
| orig directory | All the original artwork for the book
| |
| print directory | The print versions of the artwork for the book
| |
| online directory | All .gif files for the online version of the book | |
| help directory | All the helpmaps necessary for the book to act as online help for an application or utility | |
| diff directory | All the compare (CMP) and summary (SUM) files documenting the differences between this version and a previous version of the book. |
Silicon Graphics uses single-source documentation for all its technical manuals. All content is input into FrameMaker which is considered the documentation “source.”
A set of custom-designed FrameMaker templates, known as IPTemplates, are used for all Silicon Graphics books. Each template has its own set of character and paragraph catalogs and cross-reference formats. These paragraph and character tags and cross-reference formats must be used in order for the mif-to-sgm translations to work correctly. The translator and build tools include a set of styles that determine how the tags and cross-references will appear in a hard copy or online book. A more detailed description of the templates can be found in Chapter 3, “Using FrameMaker Files and IPTemplate Features.”
All English source files provided to you have been authored using the IPTemplate or have had the IPTemplate applied to them. It is unlikely that you would need to apply an IPTemplate to any documents before you translate them, but if tags or formats are inadvertently changed, a complete set of IPTempates are included with your Vendor Kit. See “Applying the Templates to Existing Files” in the IRIS InSight Professional Publisher Templates for instructions on how to apply a template.
 | Note: Do not create “custom” tags or change the cross-reference formats. This could cause errors during the bookbuild process. Silicon Graphics will not accept documents with errors. |
From the FrameMaker source, the documentation can take two different paths simultaneously. These paths are discussed in the following sections:
This is a very general overview of what happens during the conversion to online. This process starts with a FrameMaker .doc file that is saved out as a Frame Maker Interchange Format (MIF) file. An ASCII text file, the .mif file can be easily parsed by an application or script. From the mif file, a translator converts the mif into a standard generalized marker language (SGML) file. The sgml files are merged into one DynaText book. DynaText files can be viewed using a DynaText viewer. Figure 1-2 shows the process that is used for converting FrameMaker docs into an online book. Note that this process is automated with tools provided to you.
To add functionality, Silicon Graphics puts a wrapper around the DynaText viewer and calls it IRIS InSight. IRIS InSight provides capabilities such as cross-book linking; launchable universal resource locators (URLs), reference (man) pages, glossary definitions, and applications; and complete internal-book cross-referencing.
Silicon Graphics uses a Web utility from Inso Providence that automatically converts DynaText books into hypertext marker language (HTML) on the fly. This comes at a loss of functionality normally found in IRIS InSight. Silicon Graphics does nothing special to make the books show up on the Web. If you have a Silicon Graphics system with DynaWeb enabled, it views the same source that IRIS InSight views on the same system.
Using the same FrameMaker document used in Figure 1-2, PostScript files are made and sent to a print vendor to be printed.
Before you generate the PostScript files,
Paginate the FrameMaker document to remove widowed or orphaned text or list items.
Remove the master page from pages with no content, such as even pages at the end of a chapter.
Regenerate front-matter files and the index (if applicable) to update cross references.
You will not be expected to create PostScript files for books in Latin 1 languages, such as French, German, or Spanish. You may be required to create PostScript files for books using multibyte characters, such as Japanese or Korean. See the L10N specification for the list of files you'll be expected to deliver.
Silicon Graphics documents are assigned ten-digit part numbers with the format 00X-XXXX-nnn. The document's directory name is the part number, and it contains all the files required for a document. Localized documents use this part number and a two-letter language code to differentiate the part number and the document's directory from its English counterpart. For example, 007-2825-nnnJP is the Japanese version of 007-2825-nnn. Possible language codes are shown in “Part Number Language Codes for Localized Books”.
Most online or printed document part numbers begin with 007. Help books usually begin with 008. The middle four digits are the base part number, and the final three digits indicate the revision level.
A short title is condensed version of a book's full title. No more than 12 characters long, short titles are used in the Makefile for bookbuilding and as the titles of icons representing iconified IRIS InSight books.
A sample list of part numbers and their corresponding short titles are shown in Table 1-2.
Table 1-2. Document Name and Part Number Matrix
Part Number (VERSION) | Short_Title(TITLE) | Document Name (FULL_TITLE) |
|---|---|---|
007-1342-nnn | Desktop_UG | Desktop User's Guide |
007-1366-nnn | PerSysAdmin | Personal System Administration Guide |
007-1859-nnn | glossary | Silicon Graphics Glossary of Terms Global Glossary |
008-2169-nnn | HowDoI_Help | Quick Answers |
008-2172-nnn | ErrorHelp | System Monitor Errors Help |
008-2173-nnn | ErrorMessageHelp | Desktop Error Message Help |
008-2174-nnn | InsightHelp | InSight Help |
008-2181-nnn | ViewerHelp | SGIHelp Viewer Help |
007-2445-nnn | ConfTestHelp | Confidence Test Help |
007-3088-nnn | ConfTestErrors | Confidence Test Errors Help |
007-3486-nnn | NeditHelp | Nedit Help |
The two-letter language codes currently in use for books are
| DE | German | |
| ES | Spanish | |
| FR | French | |
| JP | Japanese | |
| KR | Korean |
It is important that localized document directories include this language code as a suffix. For example, the French document directory for the book 007-2825-nnn would be named 007-2825-nnnFR.
Silicon Graphics documents are usually classified as one of the following:
| Administrator | Administrator's guides | |
| Developer | Programmer's or reference guides | |
| End User | Owner's or user's guides | |
| Help | Online-only help books (these do not appear in IRIS InSight) |
Each of these types of books has its own online bookshelf in IRIS InSight. The BOOKSHELF variable in a document's Makefile determines the online bookshelf where the book appears. For a more complete description, see “Editing the Makefile”.
Make sure that the translation matches the source, or English document, as closely as possible. If extra text is added to the document, it will be difficult to update the document at a later date. For example, if the English version of a paragraph is about five lines long and the translated version is about one page long, that means you have added too much detail to the translation. When the book is revised, a compare and summary utility is used to compare the old and the new English versions. The differences in the documentation are then given to you so that you can update the old translated version. If there is extra text in the translated version, there is no utility to ensure that those longer paragraphs are updated properly in a later revision.
Make sure that the documentation matches the software which it is intended to support or document. In some cases, the documentation may reference software that requires a particular hardware item before the software will work (such as an IndyCam camera). If you do not have this equipment, contact the Silicon Graphics localization project manager and arrange either for the delivery of the hardware or for Localization to complete the consistency check.
Compare the translated version of a document against its English version. Check to make sure that:
the table of contents has the same number of headings and that they are the correct heading level
the same number of paragraphs are present
paragraphs have the same tags
characters have the same tags
cross references appear in the correct paragraph
cross references are the same in format and function
GlossaryItem-tagged words appear in the same paragraph
figures match the sofware
bullets are the correct shape
sequential lists are numbered correctly
the index shows up in the appropriate language
paragraphs tagged as Note, Shortcut, Hint, Tip, Warning, and Caution appear correctly in the appropriate language
if a glossary item is more than one word, select and tag all the words and the character space(s) between them as GlossaryItem
no text appears in English in the translated document unless appropriate or absolutely neccessary
As stated in the localization specifications sent with all source files, please consider the following points when translating a document:
Unless your localization project manager indicates otherwise, you must supply books that build error-free before they are sent to Silicon Graphics.
All books should closely match the new English source.
All character and paragraph tags should match those in the new English source.
The same number of markers should exist in both the translated books and the new English source and the markers should be the same as in the new English source.
All cross references (internal and external) must work the same as the English source.
Index markers must be translated and work properly.
There may be instances where the English source is not error-free. If the English source includes errors or warnings, there is no obligation on your part to fix these errors. These errors should be brought to Silicon Graphics' attention, however, and can be included in your periodic status reports.