django-ftl 0.12

Django implementation for Fluent, the localization system for today's world.

django-ftl is a Django package for using for Fluent, a localization system for today’s world.

This package builds upon fluent.syntax and fluent-compiler and provides:

• A structure for setting up and managing your .ftl files.

• Methods for switching/setting the current language.

• Integration into Django templates.

Why would I use this?

The defacto standard in Django world is GNU Gettext. See this Fluent vs gettext page for a comparison. In brief, here are some advantages:

• Fluent makes concerns like plural rules the job of the translator.

• Fluent gives translators the power to obey language specific rules (gender, case, plurals) that the developer may not be aware of, and shouldn’t have to build into the software.

• Fluent integrates number and date formatting, and gives both developer and translators control over these, instead of these having to be handled separately, and only controlled by the developer.

To give an example, in GNU Gettext there is support for plural rules. However, this is the only language specific feature Gettext supports, and it is kind of bolted on afterwards. The developer also has to partially hard code the English rules (that is, the fact that there are two variants in English), as per the Django docs:

msg = ngettext(
     'there is %(count)d object.',
     'there are %(count)d objects.',
 count) % {
     'count': count,
 }

Finally, this still doesn’t work very well, because often you want to special case zero anyway - “there are no objects” (or “your inbox is empty” etc.) instead of “there are 0 objects”.

In Fluent, plural rules are one example of a more generic mechanism for selecting variants, and the translator is in control. The equivalent with fluent/django-ftl, with special handling of the zero case included, looks like this in an English .ftl file:

there-are-some-objects = { $count ->
    [0]     There are no objects.
    [1]     There is one object.
    [other] There are { $count } objects.
 }

The Python code referencing this will only need to use the ID (there-are-some-objects) and pass the $count argument.

Another problem that comes up is gender - for example, in French adjectives must agree in gender with the person being described. This can be solved in Fluent by passing the gender of the person as an argument, and allowing the translator to use the variant mechanism to write the correct language. This contrasts with GNU Gettext where the developer would have to create separate message strings for each case, because the message format is not powerful enough to allow the translator to add variant selection. Also, these different message strings will be identical in languages which don’t have that feature — in other words, the grammatical features of all languages end up either having a disproportionate effect on the source code and on other translators, or being neglected entirely.

Documentation

The documentation for how to use django-ftl is in the docs/folder and online at https://django-ftl.readthedocs.io.

Status

This package should be considered a beta. While it has a good feature set, test suite and docs, it has not been used a huge amount in production.

Credits

Tools used in rendering this package:

• Cookiecutter

• cookiecutter-djangopackage

History

0.12 (2020-04-02)

• Switch to the new APIs available in fluent_compiler 0.2.

• Performance improvements - large reduction in the percentage overhead introduced by django-ftl (compared to raw fluent_compiler performance).

• Undocumented MessageFinderBase class has changed slightly: its load method now returns a fluent_compiler.resource.FtlResource object instead of a string. If you used a custom finder for Bundle you may need to update it for this change.

0.11 (2020-03-24)

• Switched to using fluent_compiler as backend instead of experimental branch in fluent.runtime. This means import changes are required:

  • fluent_number and fluent_date, if you are using them, should be imported from fluent_compiler.types instead of fluent.runtime.types

• Added Bundle.check_all method.

• Django 3.0 support

• Dropped support for Python 3.4 (it may work, but recent versions of lxml do not install on it, which made running tests harder).

0.10 (2019-05-23)

• Upgraded to more recent version of fluent.runtime (0.1 with modifications)

• Fixed use_isolating behavior (BDI characters are now inserted for HTML messages)

• Thread-safety fixes for loading bundles.

• Corrected order of using ‘locales’ directories found via INSTALLED_APPS to be consistent with normal Django convention.

0.9.1 (2019-03-02)

• Changed development autoreload mechanism to not interfere with Django’s development server autoreload.

• Bug fix for case when invalid mode is specified in template tag.

• Various fixes and improvements to middlewares (plus tests)

• Thread-safe Bundle

• Method for configuring ftlmsg via context processor.

0.9 (2018-09-10)

• Working version

• Depends on our version of python-fluent

0.0.1 (2018-05-19)

• First release on PyPI - empty placeholder package