Use simple angle brackets to separate breadcrumbs in README.
[project/i18n_boxes.git] / README.txt
1 Contents of this file:
2
3 1. Description
4 2. Installation and configuration
5 3. Usage
6 4. Troubleshooting
7
8
9 Description
10 -----------
11
12 The i18n (Internationalization) module supports translation of blocks from
13 Drupal core with i18n_block, however core blocks cannot be exported to code.
14 This module enables block titles and block content to be exported to code (via
15 the Boxes module) and then be translated (via i18n_string included with
16 the i18n module).
17
18
19 Installation and Configuration
20 ------------------------------
21
22 Note, this module requires locale, block, boxes, i18n, i18n_string, and the
23 ctools modules.
24
25 1. Download and unzip/untar the module into your Drupal site installation.
26
27 2. Ensure that the core block module is enabled before enabling i18n_boxes.
28
29 3. Enable the "Boxes translation" module, which should appear within the
30 Multilanguage section of the Module administration page.
31
32 4. Ensure the text formats you will be using for the Boxes body text are
33 translatable by visiting the "Strings" tab of the Multilingual settings page at
34 Administration > Configuration > Regional and language > Multilingual settings,
35 and checking the checkbox for the appropriate text formats.
36
37 5. Visit the Admin > Structure > Blocks page.  You will see a new option link
38 next to the "+ Add block" link called "+ Add translatable box".
39
40
41 Usage
42 -----
43
44 1. This module adds a "+ Add translatable box" link to the Block administration
45 page at Admin > Structure > Blocks.
46
47 2. After you add a translatable box, you're given the option to select the
48 Multilingual settings for the content. Select "All languages (Translatable)",
49 and specify the Box machine name, the administrative title, the Box title, and
50 the Box body -- all these should be in the site's *default language*.
51
52 3. Save the box, and enable it for display, by placing it into a region on the
53 Block administration UI (or Panel, if you use panels module).
54
55 4. Translating boxes.
56
57 There are two ways to translate boxes, via the translation interface in the
58 Drupal administrative section provided by i18n_strings module, or (optionally)
59 via the on-screen translation provided by the l10n_client module.
60
61 4.a) Translating boxes via i18n_strings
62
63 Visit the "Translate" tab of the "Translate interface" page at Administration >
64 Configuration > Regional and language > Translate interface.  Search for the
65 text strings you just created for the box title and box body by specifying them
66 in the search box. Translate them using the interface provided, for each
67 additional language you have enabled.
68
69 Visit the translated version of the page containing the translatable box to
70 verify that the string was translated. The method to change interface language
71 varies depending on how the locale module is configured for language detection
72 on your site. Refer to the locale module documentation for further configuration
73 information.
74
75 4.b) Translating boxes using the on-screen l10n_client.
76
77 Ensure the l10n_client module is enabled and configured properly, and that you
78 have permission to see the blue translation bar on the site's front-end.
79
80 Visit any page that contains the translatable box you created and enabled in
81 steps 2 and 3 above. Expand the l10n_client blue bar at the bottom of the page
82 and search for the text you wish to translate.  Specify the text and save.
83
84 5. Exporting boxes.
85
86 The default language version of each translatable box may be exported to php
87 code, typically using the Features module.  You may also wish to export the
88 translated versions from the database to .po files using the I18n module's
89 export feature.
90
91 Troubleshooting
92 ---------------
93
94 Problem: Missing "+ Add translatable box" link on Admin > Structure > Blocks.
95
96 Solution: In certain circumstances, is possible that the installation script gets run
97 before the block module (a dependency of this module) has been enabled. This
98 will cause the "+ Add translatable box" link to disappear.  Disable and reenable
99 this module to force the module weight to be higher than that of the block
100 module, which should remedy the problem.
101
102
103 Problem: The string boxes:i18n:machine_name:body for textgroup boxes is not
104 allowed for translation because of its text format.
105
106 Solution: You need to make your text formats translatable in the Multilingual
107 settings.  Go to the "Strings" tab of the Administration > Configuration >
108 Regional and language > Multilingual settings, and check the checkbox for the
109 input format(s) you intend to make translatable.