]> git.mxchange.org Git - friendica.git/blob - util/README
Correct content type
[friendica.git] / util / README
1 Utilities
2
3 php bin/console.php typo - is a crude syntax checker to avoid checking in files with simple
4 typos. It basically just loads each of our project files at once. Run from
5 cmdline and see if any parsing errors are reported.
6
7
8
9 Internationalisation
10
11 php bin/console.php extract - extracts translatable strings from our project files. It
12 currently doesn't pick up strings in other libraries we might be using such as
13 the HTML parsers.
14
15 In order for extract to do its job, every use of the L10n::t() translation function
16 must be preceded by one space. The string also can not contain parentheses. If
17 parens are required in a string which requires translation, please use hex escapes.
18
19 \x28 = (
20 \x29 = )
21
22 This only applies to English. Other languages may use parens in strings
23 because they don't require extraction.
24
25 strings.php - a recent run of the strings program. This provides output that
26 is suitable for direct inclusion in the program.
27
28 There are also translatable strings in the various files in the view/lang/en
29 directory. By setting $lang = 'something' in .htconfig.php, the application
30 will search for view/lang/something/filename prior to the English version in
31 view/lang/en/filename when loading templates and view files.
32
33 The translated string table should be placed in view/lang/$lang/strings.php for
34 automatic inclusion.
35
36 You are not restricted to using known languages. You may also use this to
37 translate the software into "pirate", "surfer" or merely to replace certain
38 text which you don't care for.
39
40 Note: The view/lang/en directory contains many HTML template files, some of which
41 only have a few words of English text amongst the HTML. Over time we will move
42 the translation to the replace_macros() function which calls these files and
43 then relocate the files to the view directory. The files in the top-level view
44 directory are template files which do not require translation.
45
46
47 Placeholders
48
49 Do not translate placeholders in strings! Things like %s, %d, %1$s and $somename
50 are used to add dynamic content to the string.
51
52 %s represents a dynamic string, like in "Welcome to %s"
53 %d represents a dynamic number, like in "%d new messages"
54 $somename is a variable like in php
55 In %1$s %2$s,  the numbers are the position index of multiple dynamic content.
56 You could swap position in string of indexed placeholders.
57 e.g.
58 "%1$s's %2$s" => "John's photo", "John's item"
59 "%2$s di %1$s" => "foto di John", "elemento di John"
60
61
62 Plural
63
64 The L10n::tt() function supports plural form. The extract command writes this in
65 strings.php as an array, one string for every plural form language supports:
66
67 $a->string["%d message sent"] = Array(
68  0 => "%d message sent",
69  1 => "%d messages sent",
70 );
71
72 The function string_plural_select($n) defined in strings.php, return the string
73 index to use, related to the numbers of item (value of $n).
74
75 This is modeled after ngettext function of GNU gettext.
76 More info at http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html
77
78
79 Xgettext and .po workflow
80
81 1. Run bin/run_xgettext.sh script (on *unix sistems, with GNU xgettext installed)
82         This script runs xgettext on source tree, extracting strings from L10n::t() and L10n::tt()
83         functions, and creates a util/messages.po file.
84
85         $ cd bin; ./run_xgettext.sh
86
87 2. copy util/messages.po to view/lang/<language>/messages.po
88         Replace <language> with the language you are working on - e.g. 'es', 'fr', 'de', etc.
89
90 3. open view/lang/<language>/messages.po with a text editor and fill in infos in
91         "Last-Translator: FULL NAME <EMAIL@ADDRESS>"
92         "Language-Team: LANGUAGE <LL@li.org>\n"
93         "Language: \n"
94
95         (eg:
96         "Last-Translator: Guybrush Threepwood <gb@host.com>"
97         "Language-Team: Pirate Friendika <pirate-friendika-ml@host.com>\n"
98         "Language: pi\n"
99         )
100
101         For the line
102         "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
103         read GNU gettext manual at
104         http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html
105
106 4. You could then translate the strings in text editor, but I suggest to use one
107         of the many .po editors out there, like QtLinguist
108
109 5. run
110         $ php bin/console.php po2php view/lang/<language>/messages.po
111         to create the strings.php file
112
113 When strings are added or modified in source, you could run
114         $ cd bin; ./run_xgettext.sh ../view/lang/<language>/messages.po
115         to extract strings from source files and join them with the existing .po file:
116         new strings are added, the existing are not overwritten.
117
118 If you already translated Friendica using strings.php, you could import your old
119 translation to messages.po. Run:
120 $ php bin/console.php php2po view/lang/<language>/strings.php