Metadata-Version: 1.1
Name: django-ftl
Version: 0.13
Summary: Django implementation for Fluent, the localization system for today's world.
Home-page: https://github.com/django-ftl/django-ftl
Author: Luke Plant
Author-email: L.Plant.98@cantab.net
License: MIT
Description: =============================
        django-ftl
        =============================
        
        .. image:: https://badge.fury.io/py/django-ftl.svg
            :target: https://badge.fury.io/py/django-ftl
        
        .. image:: https://readthedocs.org/projects/django-ftl/badge/?version=latest&style=flat
           :target: https://django-ftl.readthedocs.io
        
        .. image:: https://github.com/django-ftl/django-ftl/workflows/Python%20package/badge.svg
           :target: https://github.com/django-ftl/django-ftl/actions?query=workflow%3A%22Python+package%22+branch%3Amaster
        
        django-ftl is a Django package for using for `Fluent <https://projectfluent.org/>`_, a
        localization system for today's world. (It would have been called django-fluent but that was
        already `taken <https://django-fluent.org/>`_).
        
        This package builds upon `fluent-compiler
        <https://github.com/django-ftl/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
        <https://github.com/projectfluent/fluent/wiki/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
        <https://docs.djangoproject.com/en/dev/topics/i18n/translation/#pluralization>`_:
        
        
        .. code-block:: python
        
           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
        ------
        
        The library is now pretty stable, with a full test suite, no major missing
        features and no major breaking changes planned.
        
        It has seen real-world usage in:
        
        * `Firefox Relay <https://relay.firefox.com/>`_ - see `fx-private-relay GitHub
          project <https://github.com/mozilla/fx-private-relay>`_.
        * `Learn Scripture <https://learnscripture.net/>`_ - the original project it was
          created for, see the `GitLab learnscripture.net project
          <https://gitlab.com/learnscripture/learnscripture.net>`_.
        * Probably a fair number of other projects, but I don’t know about them…
        
        
        Credits
        -------
        
        Tools used in rendering this package:
        
        *  Cookiecutter_
        *  `cookiecutter-djangopackage`_
        
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage
        
        
        
        
        History
        -------
        
        0.13 (2021-09-16)
        +++++++++++++++++
        
        * Dropped support for Python 2.7
        * Added support for Django 3.2
        * Added support for custom functions to the Bundle constructor
        * Dropped useless mandatory configuration of ``mode`` parameter for template
          tags - it now defaults to ``'server'`` which is the only allowed option
          anyway.
        
        0.12.1 (2020-05-09)
        +++++++++++++++++++
        
        * Fixed broken (and undocumented) ``check_all`` method.
        
        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
        
Keywords: django-ftl
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.0
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
