Localizing Language Resource Files

Sandcastle uses a set of resource files to contain text such as table of contents item titles, common topic element titles, messages, etc. Copies of the resource files are located in a .\Content subfolder beneath each presentation style folder. The presentation style folders are located in the .\PresentationStyles folder in the root help file builder installation folder.

The actual content files and their names may vary by presentation style but typically include the following:

• conceptual_content.xml contains titles for items in conceptual content files.

• reference_content.xml contains titles for the various class library parts, filter text, and alternate image text.

• shared_content.xml contains paths to the shared content (art, scripts, and style sheets), code section labels, and customizable text for the header and footer in each page. The help file builder overrides many of these using its own content file.

• syntax_content.xml contains some programming language limitation messages.

• token_content.xml contains some supplemental reference messages.

The supplied files are all in English but can be translated into other languages for use in your help files. The help file builder includes its own shared content files which are used to override elements in the above files for such things as the help title, header and footer text, preliminary documentation message, etc. There are several copies of the shared content files, each representing a different language. You can find the files in the .\SHFBContent folder under the presentation style folder. Each file is named after the language for which it contains resource items. The name is the language ID based on the value returned by the CultureInfo.Name property (i.e. en-US, fr-FR, de-DE). Each file has a .xml extension.

A set of stop word list files also exists in the .\PresentationStyles\Shared\StopWordList folder that are used when creating the full text index for the website build. The files contain a list of common words that are excluded from the full-text index. This prevents the index files from getting too large and containing useless information. You can add additional words to these files as needed. The files all named using the language ID based on the value returned by the CultureInfo.Name property (i.e. en-US, fr-FR, de-DE). Each file has a.txt extension.

To create a help file builder resource file for a new language, copy one of the existing files and change the name to use the culture name's ID as described above. If you are not sure what ID to use in the filename, go to the Locale Identifier Constants and Strings help topic and locate the locale that you need. The primary language and sub-language columns contain the ID values in parentheses. Combine the two values in parentheses from those columns separated by a dash for the ID to use in the filename. Edit the new file and translate the text to the selected language. If people are kind enough to supply additional translated files, they will be added to later releases.

Due to the number of presentation styles and the number of files that would be created, it is not possible to provide a matching set of Sandcastle's content files for each language. You will need to create localized copies of them for each language that you want. As above, if people are kind enough to supply additional translated files, they will be added to later releases. The standard files in the noted .\Content folders will always be used when English (en-US) is used as the selected language or if files for the selected language cannot be found. Note that these files tend to change with each new release of Sandcastle so you may have to compare and merge changes with your localized versions after each new release is issued.

To create your own localized versions of the content files, create a folder below each of the noted .\Content folders. The new folder should be named after the selected language ID (i.e. fr-FR, de-DE, etc.). Copy the Sandcastle content files to the new language folder and translate their content. When translating shared_content.xml, be sure to set the value of the item with the locale ID to the correct language ID. When you do a build with a language other than English, the help file builder will automatically look for a folder named after the selected language and will use the translated files if it finds them. If the translated files cannot be found, a warning is issued in the log file and the English versions will be used.

How the files are encoded is very important if they contain extended characters. To ensure that the help file builder and the Sandcastle tools properly interpret the encoding within the files, it is best to save the files such that they contain byte order marks at the start of the file for Unicode encoded formats as well as an XML header tag that specifies the correct encoding. In the absence of byte order marks, the encoding in the XML header tag ensures that the file is still interpreted correctly. The supplied default language resource files contain examples of this.

When using entities to represent special characters in the XML language resource files or in the header text, copyright text, etc, use the numeric form rather than the name form as the XML parser will not recognize them and will throw an exception. For example, if you specify Ä (Latin capital letter A with diaeresis) an exception will be generated. To fix it, use the numeric form instead (Ä). This also applies to symbols such as © in the copyright text. Instead, you should use © to get the copyright symbol.

Other Resources