A gettext-style internationalisation framework for Common Lisp.

cl-i18n



* Prerequisites:
- ASDF
- uiop (if your ASDF version is < 3)
- cl-ppcre
- alexandria
- babel

* Installation:

The  best  way   to  get  cl-i18n  working  is   using  the  excellent
[[http://www.quicklisp.org/][quicklisp]]

#+BEGIN_SRC common-lisp
(ql:quickload "cl-i18n")
#+END_SRC

* Usage
  This library can load translations from file formats of the following types:
- [[https://www.gnu.org/software/gettext/][GNU gettext]] text file (AKA PO files);
- [[https://www.gnu.org/software/gettext/][GNU gettext]] binary file (AKA MO files);
- [[https://web.archive.org/web/20190407131733/https://www.aamt.info/english/utx/index.htm][Universal Terminology eXchange]] format
- its native file formats (essentially a Common lisp S-exp).

Check the ~examples/~ directory for an usage example.

** Extracting translatable strings:

#+BEGIN_SRC common-lisp
  ;; define two convenience functions

  (defun _ (a) (cl-i18n:translate a))

  (defun n_ (s f n) (cl-i18n:ntranslate s f n))

  (cl-i18n-utils:gen-translation-file "/src/" "klingon.lisp"
                                      :ext "lisp$"
                                      :prefix-re "\\(_\\s+")

  (cl-i18n-utils:gen-translation-file "/src/" "klingon.lisp"
                                      :ext "lisp$"
                                      :prefix-re "\\(n_\\s+")

#+END_SRC

   Will extract  all ~(_…~   strings from  all the
   files in directory  ~/src~ which name ends in "lisp"  and set up a
   basic translation resource in  klingon.lisp (*Note: the output file
   if exists will be overwritten*).

   To make it work with CL-WHO, use the “str” directive, as in

#+BEGIN_SRC common-lisp
  (with-html-output *out*
    (:p (str (_ "Peace and love!"))))
#+END_SRC

   Please note that the library can accept gettext MO or PO files so
   nothing prevents you using GNU xgettext to extracts strings that needs to
   be translated and use its output as translation file.

** Locating GNU message catalog files

According to
[[https://www.gnu.org/software/gettext/manual/gettext.html#Locating-Catalogs][GNU
gettext  manual]] the  path to  the catalog  is system  dipendent, the
function  /search-mo-repository/ will  try  to figure  out where  that
catalog  *could*  be;  but  its  implementation  is  slow,  memory
consuming and sometimes fails (i.e. crash).

** Simple example

Here is  a way similar  to GNU gettext  style API; please note  we are
assuming  ~/usr/share/locale/~ as the  path where  the catalog  can be
found and foo.mo is there.

We also let the library guess the right locale with ~find-locale~.

#+BEGIN_SRC common-lisp
  (let ((*translation-file-root* "/usr/share/locale/"))
    (load-language "foo" :locale (find-locale))
    (format t "~a~%" (_ "Browse"))
    (format t "~a~%" (_ "Save as...")))
#+END_SRC

* String utils

  During the development of this library I have implemented a couple of string functions that I think could be useful beyond i18n.

  - cl-i18n-utils:levenshtein-distance (string1 string2) :: Compute the levenshtein distance (i. e. how much are similars) between two strings

  - cl-i18n-utils:fuzzy-match (...) ::  Performs a Smith-Waterman affinity search.
   See: https://en.wikipedia.org/wiki/Smith%E2%80%93Waterman_algorithm

* Old version incompatibility

This version deeply changed the  file format of the translation table,
however you can convert from the old format to the new one with:

#+BEGIN_SRC common-lisp
  (cl-i18n-utils:convert-save-dictionary oldfile-path new-filepath)
#+END_SRC

*Note: the output file if exists will be overwritten*

* Bugs and issues

Please file bug report on
the [[https://codeberg.org/cage/cl-i18n/issues][issue tracker]].

** Known issues
- Documentation is missing;
- Source code is mostly undocumented;
- PO file parser is slow.

* License
  This library is released under Lisp Lesser General Public license (see
  COPYING.LESSER file)

  Examples are released under GPL version 3 or later

  =doc/internals/pofiles_grammar=  is ©  2012 cage  and is  licensed under
  Creative Commons Attribution-ShareAlike 3.0 Unported

  File /function-name.lisp/ was got from
  [[http://common-lisp.net/project/cl-store/][cl-store]] © 2004 Sean Ross and
  included here with the original license stated below.

  Copyright (c) 2004 Sean Ross
  All rights reserved.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:
  1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
  3. The names of the authors and contributors may not be used to endorse
    or promote products derived from this software without specific prior
    written permission.

  THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  SUCH DAMAGE.

* NO WARRANTY

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

* Contributors:

- Leslie P. Polzer  (base)
- Vilson Vieira     (string extractor)
- Cage              (developer and maintainer)


cl-i18n

Upstream URL

Author

Maintainer

License

cl-i18n

Version:

License:

Authors:

Maintainers:

Dependencies:

cl-i18n/tests

License:

Authors:

Dependencies:

Dependencies (4)

Dependents (0)