README.md
1Locale::Maketext::Gettext - Joins the gettext and Maketext frameworks
2=====================================================================
3
4Locale::Maketext::Gettext joins the [GNU gettext] and [Maketext]
5frameworks. It is a subclass of Locale::Maketext that follows the
6way GNU gettext works. It works seamlessly, both in the sense of
7GNU gettext and Maketext. As a result, you enjoy both their
8advantages, and get rid of both their problems, too.
9
10You start as a usual GNU gettext localization project: Work on
11PO files with the help of translators, reviewers and Emacs. Turn
12them into MO files with `msgfmt`. Copy them into the appropriate
13locale directory, such as
14`/usr/share/locale/de/LC_MESSAGES/myapp.mo`.
15
16Then, build your Maketext localization class, with your base class
17changed from Locale::Maketext to Locale::Maketext::Gettext. That's
18all. ^_*'
19
20[GNU gettext]: https://www.gnu.org/software/gettext/
21[Maketext]: https://perldoc.perl.org/Locale::Maketext
22
23
24Locale::Maketext::Gettext::Functions
25------------------------------------
26
27Locale::Maketext::Gettext::Functions is a functional
28interface to Locale::Maketext::Gettext (and Locale::Maketext).
29It works completely the GNU gettext way. It plays magic to
30Locale::Maketext. No more localization class/subclasses and language
31handles are required.
32
33
34The `maketext` script
35---------------------
36
37The `maketext` script is a command-line interface to
38Locale::Maketext::Gettext (and Locale::Maketext). It can be used in
39shell scripts, etc, to translate, maketext and return the
40result. It enables Maketext to be integrated into other programming
41languages/systems, like bash/csh, python, PHP, C, etc. It works
42like the command-line program `gettext`.
43
44
45System Requirements
46-------------------
47
481. Perl, version 5.8.0 or above. Locale::Maketext::Gettext uses the
49 utf8 text internally that is only available since 5.8.0. You can
50 run `perl -v` to see your current Perl version. If you don't have
51 Perl, or if you have an older version of Perl, you can download and
52 install/upgrade it from the [Perl website]. If you are using
53 MS-Windows, you can download and install [ActiveState ActivePerl].
54
552. Required Perl modules: None.
56
573. Optional Perl modules: None.
58
59[Perl website]: https://www.perl.org
60[ActiveState ActivePerl]: https://www.activestate.com
61
62
63Download
64--------
65
66Locale::Maketext::Gettext is hosted is on…
67
68* [Locale-Maketext-Gettext on GitHub]
69
70* [Locale-Maketext-Gettext on MetaCPAN]
71
72[Locale-Maketext-Gettext on GitHub]: https://github.com/imacat/Locale-Maketext-Gettext
73[Locale-Maketext-Gettext on MetaCPAN]: https://metacpan.org/release/Locale-Maketext-Gettext
74
75
76Install
77-------
78
79### Install with [ExtUtils::MakeMaker]
80
81Locale-Maketext-Gettext uses standard Perl installation with
82ExtUtils::MakeMaker. Follow these steps:
83
84 % perl Makefile.PL
85 % make
86 % make test
87 % make install
88
89When running `make install`, make sure you have the privilege to write
90to the installation location. This usually requires the `root`
91privilege.
92
93If you are using ActivePerl under MS-Windows, you should use `nmake`
94instead of `make`. [nmake can be obtained from the Microsoft FTP site.]
95
96If you want to install into another location, you can set the
97`PREFIX`. For example, to install into your home when you are not
98`root`:
99
100 % perl Makefile.PL PREFIX=/home/jessica
101
102Refer to the documentation of ExtUtils::MakeMaker for more
103installation options (by running `perldoc ExtUtils::MakeMaker`).
104
105
106### Install with [Module::Build]
107
108You can install with Module::Build instead, if you prefer. Follow
109these steps:
110
111 % perl Build.PL
112 % ./Build
113 % ./Build test
114 % ./Build install
115
116When running `./Build install`, make sure you have the privilege to
117write to the installation location. This usually requires the `root`
118privilege.
119
120If you want to install into another location, you can set the
121`--prefix`. For example, to install into your home when you are not
122``root``:
123
124 % perl Build.PL --prefix=/home/jessica
125
126Refer to the documentation of Module::Build for more
127installation options (by running `perldoc Module::Build`).
128
129
130### Install with the CPAN Shell
131
132You can install with the CPAN shell, if you prefer. CPAN shell
133takes care of ExtUtils::MakeMaker and Module::Build for you:
134
135 % cpan Locale::Maketext::Gettext
136
137Make sure you have the privilege to write to the installation
138location. This usually requires the `root` privilege. Since CPAN
139shell 1.81 you can set `make_install_make_command` and
140`mbuild_install_build_command` in your CPAN configuration to switch
141to `root` just before install:
142
143 % cpan
144 cpan> o conf make_install_make_command "sudo make"
145 cpan> o conf mbuild_install_build_command "sudo ./Build"
146 cpan> install Locale::Maketext::Gettext
147
148If you want to install into another location, you can set `makepl_arg`
149and `mbuild_arg` in your CPAN configuration. For example, to install
150into your home when you are not `root`:
151
152 % cpan
153 cpan> o conf makepl_arg "PREFIX=/home/jessica"
154 cpan> o conf mbuild_arg "--prefix=/home/jessica"
155 cpan> install Locale::Maketext::Gettext
156
157Refer to the documentation of cpan for more CPAN shell commands
158(by running `perldoc cpan`).
159
160
161### Install with the CPANPLUS Shell
162
163You can install with the CPANPLUS shell, if you prefer. CPANPLUS
164shell takes care of ExtUtils::MakeMaker and Module::Build for you:
165
166 % cpanp -i Locale::Maketext::Gettext
167
168Make sure you have the privilege to write to the installation
169location. This usually requires the `root` privilege.
170
171If you want to install into another location, you can set
172`makemakerflags` and `buildflags` in your CPANPLUS configuration.
173For example, to install into your home when you are not `root`:
174
175 % cpanp
176 CPAN Terminal> s conf makemakerflags "PREFIX=/home/jessica"
177 CPAN Terminal> s conf buildflags "--prefix=/home/jessica"
178 CPAN Terminal> install Locale::Maketext::Gettext
179
180Refer to the documentation of `cpanp` for more CPANPLUS shell
181commands (by running `perldoc cpanp`).
182
183[ExtUtils::MakeMaker]: https://metacpan.org/release/ExtUtils-MakeMaker
184[nmake can be obtained from the Microsoft FTP site.]: ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
185[Module::Build]: https://metacpan.org/release/Module-Build
186
187
188Source
189------
190
191Source is now on Github. See
192https://github.com/imacat/Locale-Maketext-Gettext.
193
194
195Support
196-------
197
198The Locale-Maketext-Gettext project is hosted on GitHub. Address your
199issues on the GitHub issue tracker
200https://github.com/imacat/Locale-Maketext-Gettext/issues.
201
202
203News, Changes and Updates
204-------------------------
205
206Refer to the Changes for changes, bug fixes, updates, new functions, etc.
207
208
209Thanks
210------
211
212* Thanks to [Max Maischein] for reporting CPAN tester failures 200029,
213 200332 and 200331, that helps me find the shell character escape
214 problem on my test suite.
215
216* Thanks to [Andreas Koenig] for reporting CPAN tester failures 387357
217 and submitting [rt bug 23956], informing me the base class
218 Locale::Maketext has updated its error handling behavior in the Perl
219 5.9.
220
221* Thanks to [Chris Travers] for suggestion to implement `pgettext()`
222 in GNU gettext as `pmaketext()`.
223
224[Max Maischein]: mailto:corion@corion.net
225[Andreas Koenig]: mailto:andk@cpan.org
226[rt bug 23956]: https://rt.cpan.org/Public/Bug/Display.html?id=23956
227[Chris Travers]: mailto:chris.travers@gmail.com
228
229
230To Do
231-----
232
233* Design a way to install the MO file through ExtUtils::MakeMaker and
234 Module::Build.
235
236
237Copyright
238---------
239
240 Copyright (c) 2003-2021 imacat. All rights reserved. This program is free
241 software; you can redistribute it and/or modify it under the same terms
242 as Perl itself.
243