Flare supports authoring and output for left-to-right (LTR) as well as right-to-left (RTL) languages. This includes English, French, German, Japanese, Chinese, Arabic, Persian, Hebrew, double-byte languages, and more. RTL languages are supported in all outputs except DotNet Help and FrameMaker. Flare supports bi-directional languages not only at the topic level, but all the way down to the paragraph and sentence level. If you have a sentence containing both LTR and RTL languages, Flare will treat each of them appropriately in that sentence.
You can select a language for a project, target, topic, or even specific content. Selecting a language affects spell checking as well as the language skin used. See Selecting a Language.
Full authoring of LTR and RTL text is supported in Flare's XML Editor.
The XML Editor supports the following related to RTL.
- RTL text is readable and can be edited in the XML Editor.
- Flare supports CSS and HTML direction properties (e.g., "direction: rtl" and dir="rtl"). If these properties are set to "right," the following occur.
- Text is right-aligned.
- Tables flow from the right to left (i.e., cell 1 is at the top right, cell 2 is to the left of it).
- List item bullets and numbers are to the right of their content instead of left.
- If an RTL language has been selected for the project or topic, the default direction for content is right-to-left. On the other hand, if an LTR language is selected, the default direction is left-to-right.
A language skin can be used to display the interface in a specific language for online outputs. Language skins hold only text used for the output; they do not control the look of the output. To control the appearance of the output, you must use a regular skin in addition to the language skin. See About Language Skins.
The language set at the project or target level affects the skin used for the output if you are generating WebHelp outputs. Flare provides completed language skins for certain languages, such as French, German, Spanish, and more. You can customize these language skins with your own translations, as well. For other languages, you can create language skins. See Creating User-defined Language Skins and Editing Language Skins.
Let's say you select French as the project language. If you generate WebHelp, the French skin is automatically used, so the output looks something like this.
Note: Typically, language skins are designed for online Help outputs only (HTML5, WebHelp, WebHelp AIR, WebHelp Mobile, and WebHelp Plus).
However, if you are editing text strings in a language skin for toolbar items, those strings will be translated in DotNet Help and Microsoft HTML Help outputs as well.
In addition, the "Formats/Cross-Reference" items in the Language Skin Editor are used for both print-based and online outputs. Those items are intended to set text for context-sensitive cross-references.
Another print-based feature controlled in the language skin is the heading text for auto-generated glossaries, indexes, and proxies.
Language skins also control features found in MadCap Feedback, such as comment labels and profile items.
If you have translated your project into other languages, you can link Lingo projects or additional translated Flare projects to your master project to create multilingual output
Flare will create a subfolder in your Output folder for each language. When you view the output, Flare will display the output for your browser's default language. In HTML5 outputs, you can use a drop-down menu to switch between each generated language.
Note: Be sure that the file names are the same in your master project and each of your linked projects. This is especially important for HTML5 targets, so you can switch between languages using the Select Language button in the output.
Note: If you are using an HTML5 output, be sure to enable the SelectLanguage button in the skin for your master project and each linked project. This will allow you to change languages using a drop-down.
If you are creating Top Navigation output, you should have a Topic Toolbar skin component in your project
(see Adding Skins and Topic Toolbars in HTML5 Skin Components). Open the skin component, and select the Setup tab.
If instead you are creating Tripane output, open the regular skin and select the Toolbar tab.
If necessary, move the SelectLanguage button from the Available section to the Selected section.
After you add the SelectLanguage button to your Topic Toolbar, you also need to be sure the toolbar appears in your master page. If the topic toolbar does not appear in each of your master pages, you will not be able to switch languages from those page types.
The output is merged (or “stitched”) into a single document, with each language appearing in the order you specified. You will see a single file in your Output folder.
Note: Generating a PDF output using a multilingual target uses the same process as PDF stitching
Note: You can access individual PDFs for each language in the Temporary folder in your Output folder.
Flare will create subfolders for each language in your Output folder. You can merge printed output types manually (e.g., in Word) if you need to create a single file.
Note: If you are building Eclipse Help, you will need to open your Output folder to open your desired language output.
Following are two examples of multilingual output.
In the first example, a Flare target points to other Flare projects that have been translated. This example also illustrates the process of adding a button (via a skin) so end users can switch between languages in online output. It also demonstrates out PDF output is generated from a multilingual project.
In the second example, a Flare target points directly to Lingo projects. This is a more direct approach because it doesn't require the creation of additional Flare projects.
Example—Linking to Flare Projects
Let’s say you want to create HTML5 and PDF outputs in US English, Spanish, and Japanese. You have already worked with a translator to translate your documents, so you have three different Flare projects: one for each language.
Before you can create your multilingual output in Flare, make sure that each Flare project has both an HTML5 and a PDF target available. This will allow your master project to build from the targets in the other two linked projects. Open the Project Organizer in each project, and then open the Targets folder. If you already have the targets you need, you do not need to create any new targets. If you do not have both targets in all three projects, you can create the missing targets from the Add File dialog.
Because you want to build multilingual HTML5 output, you need to make sure that each of your projects has the SelectLanguage button in its HTML5 toolbar. If it the button isn't there, users won't be able to switch from one language to another in your output.
Open the Project Organizer. In the Skins folder, open the Topic Toolbar skin component. On the Setup tab, select the SelectLanguage button, click to add it to your skin, and then save your work.
Now you can prepare your multilingual target. Open your master project (in this case, the US English project), and open the Targets folder. Open the HTML5 target. In the Target Editor, select the Language tab. This is where you will link your other two projects. Click to add a new row.
Click the link in the Linked Flare Project column.
In the dialog that opens, navigate to your Spanish project and click Open. This links the Spanish project to the US English project. The Language drop-down automatically updates when Flare detects the default Spanish language settings in your linked project.
Add your Japanese project in the same way.
You want the Japanese project to appear second in the Help system, so you select the Japanese project and click to rearrange the projects.
Now the Japanese project is listed before the Spanish project.
You are ready to build, so save your work and build the target. When you open the HTML5 output, it defaults to the US English Help because that is your browser’s default setting.
But remember the SelectLanguage button you added to your Topic Toolbar skin component? You can use that button to change the language setting using a drop-down menu.
Next you create the PDF target. Open the PDF target in the Target Editor and create it in the same way you did the HTML5 output. Since you want the Japanese output to appear first, you add that project first, then you add the Spanish project.
Save the PDF target and build it. When you look in the Output folder, you only see one document. This is because Flare stitched all three documents together into a single PDF.
When you open the PDF, you see all three languages in the document’s table of contents. Each language has its own title page so you can find it quickly.
Example—Linking to Lingo Projects
Let's say want your Flare project to be translated into Arabic, French, German, and Spanish. You have one translator who knows French, German, and Spanish, and you have a second translator who knows Arabic.
Because the first translator knows three languages, there is no reason to have multiple Lingo projects for each language. Instead, the translator adds all three languages to a single Lingo project and translates the files.
Meanwhile, the second translator creates a second Lingo project and uses it to translate the Flare project into Arabic.
Both translators keep their Lingo projects on a server where you have access them. When the translation work is finished, you open your target in Flare, and on the Language tab, you add a row for each language.
In the first row, you link to the Lingo project that was used for the French, German, and Spanish translations. After you add the first row, you notice that you can select any of the three languages.
For the first row, you select French. Then you add a second row. This time, you can only select German or Spanish (because French has already been used).
For the second row, you choose German. Then you add a third row. Spanish is automatically chosen for that row, because it is the only one left.
Finally, you create a fourth row and link it to the Lingo project used for the Arabic translation.
Note: You can use a tool like MadCap Lingo (or another computer-aided translation tool) to translate your Flare content. Although you can set the language for your project in Flare, this does not mean that Flare automatically outputs translated content.
Note: You must link each language to a Flare or Lingo project before you can close the Target Editor. Similarly, if you make changes to your linked projects and their links are no longer valid when you build the project, you will see a warning message before the build starts and you will be unable to build.
Note: In order to build output that links directly to multilingual Lingo projects, the Flare user must have Lingo 10 installed on the same computer.
Note: When you build a target that is set up for multilingual output and you link directly to a Lingo project, the export process runs automatically in Lingo so that the master Flare project can grab the necessary translated Flare projects. If the Lingo export process encounters warnings, these will not display with the other build warnings in Flare's interface. Instead, you must open the build log to find any such warnings.
Note: Because Flare generates output from the linked targets in each of your project files, each linked project must have its own target file for the output you want to build (e.g., if you are creating PDF output, each linked project needs its own PDF target). If you do not have a needed target file in one of your linked projects, you will see a warning message before the build starts and you will be unable to build. Target files must be in the same relative location in each project.
Note: If you have created a new language skin for a language, Flare will use it when you build the project. The language skin must reside in the project that uses that language.
Note: If you are using right-to-left language settings in a linked project, you must enable these settings in your master project target. Language settings in the master project target control those for each of the linked projects, regardless of the settings in your linked projects.
In the Language tab for the target there are multiple options that are selected by default when you choose an RTL language at the project or target level. The options are used to automatically invert the following: (1) language-related style rules locally, (2) language-related style rules in the stylesheet, (3) image callouts from MadCap Capture, and (4) page layout settings. See Selecting a Language.
The options that are seen depend on which output type you are using.
- PDF/XPS/XHTML/Word All four options are shown.
- HTML5/HTML Help/EPUB/All WebHelps Local styles, CSS styles, and image callout options are shown.
- DITA/DotNet Help/FrameMaker No options are shown (FrameMaker and DotNet Help do not support RTL languages).
These options can be quite useful after you receive the project back from a translator. When you generate the output, the inversion of the styles and page layouts takes place.
Let's say you have a project in English (a left-to-right language), and you need to have it translated into Arabic (a right-to-left language).
For your p style, suppose you have a left margin of 5 px and a right margin of 30 px.
Those settings work fine for your targets using the LTR language. But for the RTL language, you need the settings to be flipped so that the left margin is 30 px and the right margin is 5 px.
So after you receive the project back from the translator, you make sure the RTL language in Flare is set at either the project or target level.
As a result, the inversion options become selected automatically, and when you generate the output, paragraphs will have a left margin of 30 px and a right margin of 5 px.
Note: If your selected language is LTR, these options cannot be accessed in the Target Editor.
There are certain features in Flare that use special hotspot images (e.g., drop-down and expanding text effects). Flare's default images for these features are designed to work with LTR outputs. However, if you are using an RTL language, Flare automatically inverts the default images so that they make sense for that direction as well.
Let's say you have an English project with drop-down effects, like this:
If you look at the same topic in an Arabic project, it will look like this:
This inversion occurs in any of the following features that use hotspot images.
- Drop-Down Text
For more information, see Editing Drop-Down Text.
- Expanding Text
For more information, see Editing Expanding Text.
For more information, see Editing Togglers.
- Concept Links
For more information, see Editing Concept Links.
- Keyword Links
For more information, see Editing Keyword Links.
- Related Topics
For more information, see Editing Related Topics Links.
For more information, see Editing Shortcut Controls.
Note: Custom images that you create and add are not inverted. If you want to have inverted versions of an image, you need to use two different skins—one for the LTR images and a second for the RTL images.
If you are using an RTL language, table styles in your project need to write additional CSS rules behind the scenes in order to work correctly with RTL tables. Because this can potentially double the size of the table style file, this behavior does not happen by default if you create and save a new table style. However, the behavior kicks in automatically in the following two scenarios.
- If you open a topic in the XML Editor and an RTL table references an old table stylesheet, Flare updates and saves the table stylesheet in your Content folder.
- If you generate output and an RTL table references an old table stylesheet, the table style in the output will be updated.
Several languages come with built-in spell checking support in Flare. You can see which dictionaries are installed on your computer by opening the Options dialog and selecting the Spelling tab.
Green dots indicate which dictionaries support spell checking and which support hyphenators. A hyphenator is used to automatically hyphenate words in an editor based on particular word patterns, as outlined in the dictionary file. (Hyphenators are important only for certain languages.)
You can download more dictionaries from openoffice.org. After you download a new dictionary, you can install it by clicking Import Dictionaries at the bottom of the Options dialog in Flare. See Importing Dictionaries.
Note: For more information about hyphenation patterns in different languages, see http://hunspell.sourceforge.net/tb87nemeth.pdf.
Note: Dictionaries are stored in your AppData Windows folder.
After completing a project in one language, you might need to have it translated into another language.
MadCap Lingo One of the easiest ways to translate a Flare project is for a translator to open that project within MadCap Lingo, which is tightly integrated with Flare. Because of this integration, there is no need to transfer localized files outside of the actual project, which helps prevent content and formatting corruption. In addition, translators can leverage all previous translations created in other tools by importing Translation Memory eXchange (TMX) files.
After opening your project in Lingo, a translator can immediately see a list of all of the files (e.g., topics, snippets, variables), index markers, and concept markers than need to be localized. Then, after translating the content in the Lingo interface, the translator can export the results to a new Flare project in that language. For more information, please refer to the documentation provided with MadCap Lingo.
- Third-Party Translation Tools Each file in a Flare project is XML-based and accessible in third-party tools. You can even use MadCap Lingo to package your project files and send them to a translator who is using another tool. That way, the translator receives all of the files requiring translation. It makes things easier for the translator, who receives a complete list of files that he or she can import into the third-party tool; no guessing is required. It also makes things easier for you as the author, because you do not need to worry about forgetting to send often-missed Flare project files that require translation and can easily be overlooked. For more information, please refer to the documentation provided with MadCap Lingo.
You can export an entire Flare project, or parts of one, to another location. One reason you might want to use this feature is to quickly and easily archive projects, especially if you have an extremely large Flare project and need to archive only parts of it. Another use for this feature is translation. If you only need a portion of a master project to be translated, you don't want to send the translator all of the files, but rather a smaller version of the project containing only the files requiring translation.
Let's say you have a Flare project with seven targets you need to translate the content associated one of those targets from English to French. You could send your entire Flare project to the translator, but that would mean the translator would be getting files associated with all seven targets, not just the one requiring translation. So you decide to export only the portion of the Flare project that needs to be translated.
First, from the Project ribbon you click Export Project. On the first page of the wizard, you click in the Export From drop-down and select Using Target.
On the next page of the wizard, you select the target whose files you want to export. In this case, let's say the target in question is named "Product1_Web Output." In addition, you tell Flare to convert your variables and snippets to text so that they become part of the topics, rather than separate files.
After clicking Finish, the relevant files and content are exported to a new, smaller Flare project. Only the files and content necessary to produce the Product1_Web Output target are included in the export. Therefore, the translator receives only the files requiring translation.
You can stitch existing PDFs into your output by adding links to them in a table of contents (TOC). This is supported in PDF output and all of the online targets.
The PDF stitching feature can be especially useful if you have created multiple PDF versions of your documentation in different languages. Each existing PDF could be a version of the content in a unique language.
Let's say you have an English project, which you send away to be translated into Arabic, French, and Spanish. At the end of the translation process, you've got three PDF files, one for each of those languages.
In Windows, you copy those three PDFs into the Content subfolder where your project is located.
In Flare you open the TOC that you are using to generate the PDF output for your English content. Then you drag and drop the three PDFs to the bottom of that TOC.
You don't necessarily need to put the PDFs at the end of the TOC; they can actually be placed anywhere. But we put them at the bottom because we want the final stitched PDF to move in order from English to Arabic to French to Spanish.
After generating the final PDF target, the other PDFs are stitched into the output along with the English content.
Note: Generating a PDF output using a multilingual target uses the same process as PDF stitching
Note: The freely distributable MadCap Help Viewer also supports multiple languages in the interface (English, French, German, and Japanese). Therefore, if you build and distribute DotNet Help, users will be able to select from the available languages to view the interface for your online Help.
Note: When generating localized HTML Help targets, it is sometimes necessary to set the Windows system locale to match the language that the project is set to. It is necessary to do this when the project contains topic file names with non-English characters. To do this in Windows: 1. Open the Control Panel; 2. select Regional and Language Settings; 3. select the Advanced tab; 4. from the drop-down in the section called Language for non-Unicode programs, choose the same language that the Flare project is set to; 5. restart Windows.
Note: Using the external version of MadCap Analyzer, you can generate a language report. This report shows each file where a language tag is found, the content tag to which it has been applied (e.g., html, span), and the language used.
Note: If you have inserted MadCap Capture images that contain objects with text, you can auto-size those objects automatically when the output is generated. This can be done by selecting an option in the Advanced tab of the Target Editor. The original image file and its associated properties (.props) file remain unchanged. Only the output image is affected. You might use this option in case you accidentally cut off text in your image callouts or if they are translated into another language that requires more characters in the translation.