Hi fellow translators,
I've been working that new-feature ticket starting with an idea Jannis
Leidel had posted in a GitHb [0]Gist some months ago and would like to
get some feedback from developers with real i18n experience about this
first iteration of a [1]patch for it.
Solving this would allow Django to support in a better way translation
of model names to a wider range of locales and could help with ticket
[2]#14844 by providing a base infrastructure for fixing it.
A brief description of the user-facing part of the proposed
implementation:
NOTE: The names are up for replacement in case they are too ugly too
generic or too prone to clash with existing code. I myself have renamed
them twice already (fortunately it is mostly a mass search and replace
operation).
It is composed of two parts:
Part 1:
=======
A new, optional
@classmethod
def verbose_names(cls, count=1)
that can be implemented by the programmer in her model. It is in charge
of returning the verbose name corresponding to /count/ model instances.
This means:
* The now deprecated Meta.verbose_name and Meta.verbose_name_plural
options have been promoted from the Meta inner class to the model
scope itself.
* Singular and plural forms treatment is unified by delegating in this
single method the job of returning them based on the value of
the /count/ parameter. Plural forms aren't limited to two (singular
case plus one plural form) as in English and most western European
languages.
Simple example for audience group #1: Authors of apps whose users use
and will always use one locale (e.g. English) so they set USE_I18N=False
and don't need to care for i18n::
1 class DjangoMascot(models.Model):
2 ...
3
4 @classmethod
5 def verbose_names(cls, count=1):
6 if count == 1:
7 return 'flying pony'
8 else:
9 return 'flying ponies'
verbose_names() can ignore one or more values of /count/ and implement
returning a valid verbose name only for certain values of such argument.
In that case Django will make sure default fallback values are provided
to consumers (see description of the public API in Part 2 and backward
compatibility sections below), e.g.::
1 class Poll(models.Model):
2 ...
3
4 # Developer didn't provide a verbose_names() classmethod.
5 # Django provided fallbacks means 'poll' and 'polls'
6 # will be returned when Poll.get_verbose_name(1) and
7 # Poll.get_verbose_name(<any values different from 1>) are
8 # called, respectively.
Other example::
1 class FirewallPolicy(models.Model):
2 ...
3
4 @classmethod
5 def verbose_names(cls, count=1):
6 if count != 1:
7 return 'firewall policies'
8 # Django provided fallback means 'firewall policy'
9 # will be returned when FirewallPolicy.get_verbose_name(1)
10 # is called
Example for audience group #2: Authors of i18n-aware apps and that
because of that use USE_I18N=True and functions from
django.utils.translation:
What currently is expressed in this fashion::
1 from django.utils.translation import ugettext_lazy as _
2
3 class Library(models.Model):
4 city_name = models.CharField(max_length=30)
5
6 class Meta
7 verbose_name = _('llbrary')
8 verbose_name_plural = _('llbraries')
Will need to be converted to this::
1 from django.utils.translation import ungettext_lazy
2
3 class Library(models.Model):
4 city_name = models.CharField(max_length=30)
5
6 @classmethod
7 def verbose_names(cls, count=1):
8 return ungettext_lazy('llbrary', 'libraries', count)
The fact that we can use ungettext_lazy() means that the gettext PO
catalog entries for this model will change from::
#: foo/models.py:7
msgid "library"
msgstr "<translation of 'library'>"
#: foo/models.py:8
msgid "libraries"
msgstr "<translation of 'libraries'>"
To this::
#: foo/models.py:8
msgid "library"
msgid_plural "libraries"
msgstr[0] "<translation of 'library' with plural form #1>"
...
msgstr[n] "<translation of 'library' with plural form #n+1>"
This is semantically more complete and will allow locales with more than
two plural forms to have better translations of phrases that involve
arbitrary quantities of Django models. E.g. Polish (pl) has three plural
forms and Irish (ga) has five.
Part 2:
=======
A django.db.Model.get_verbose_name(cls, count=1): classmethod that
provides a published API to obtain different flavors of verbose names of
the model at hand.
It is always available so it is always possible to get verbose
names of any model. This method isolates code that needs to get human
readable representations of model names from the particularities of
the verbose_names() model method described in Part 1, if any.
This method will seldomly be overridden by developers if at all. It's
implemented in the base Model class and contains the logic for backward
compatibility and to cope with the possible behaviors of user-provided
verbose_names().
All internal uses in Django itself have been converted to use this API.
Previously this was implemented by reading
<Model class>._meta.verbose_name and
<Model class>._meta.verbose_name_plural
Backward compatibility
----------------------
Backward compatibility has been implemented in a way such that:
o The presence of a verbose_names() classmethod in a model definition
has precedence over the Meta.verbose_name and
Meta.verbose_name_plural options
o Also, these options get their values from internal calls to this
method to preserve compatibility with other apps/code that will keep
using them during a transition period.
o The fallback get_verbose_name() return values in case the developer
doesn't implement verbose_names() (or implements it partially) in a
given model are the same Django has us accustomed to when we didn't
specify Meta.verbose_name and/or Meta.verbose_name_plural i.e.:
* CamelCase -> 'camel case' transformation for the singular case
* Singular verbose name + 's' for the plural case.
Deprecation process
-------------------
As implemented in the patch, currently PendingDeprecationWarning is
raised (one needs to specify the -Wall command line switch to the Python
interpreter to see them) when:
* Meta.verbose_name or Meta.verbose_name_plural are specified
in a model definition
* Model._meta.verbose_name or Model._meta.verbose_name_plural
are accessed (read) (implementation note: They've been converted
into properties)
In Django 1.4+1 the warnings will be changed to DeprecationWarning
Starting with Django 1.4+2 Meta.verbose_name and
Meta.verbose_name_plural will be ignored.
(Open) questions/Things that could be changed
---------------------------------------------
* Is it ok to add (class)method's to Model?, there is the possibility
of name clash with equally named existing attributes/method names in
user models.
* Should we make verbose_names() count argument not have a default value
(=1) and so make it mandatory to specify a value of model quantity?
* Why are these classmethods? Because there isn't anything in these
methods that might make them depend on a given model instance
characteristics to do their job and because many uses from other parts
of Django don't have a model instance at hand but rather the model
class.
* Further, maybe actually there is even no need to them be classmethods
and we can make them staticmethods?
* Can we drop the setter in the now properties _meta Option verbose_name
and verbose_name_plural? This would effectively convert them in
read-only options because we never officially supported modification
of these options at runtime.
Patch status
------------
Patch is in good shape, has documentation changes and tests although
I plan to expand them more.
Any kind of feedback is welcome!
0. https://gist.github.com/2000f763e15c260c0666
1.
https://code.djangoproject.com/attachment/ticket/11688/11688-verbose_name_plural_evolution-1.diff
2. https://code.djangoproject.com/ticket/14844
Regards,
--
Ramiro Morales
--
You received this message because you are subscribed to the Google Groups
"Django internationalization and localization" group.
To post to this group, send email to django-i18n@googlegroups.com.
To unsubscribe from this group, send email to
django-i18n+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-i18n?hl=en.
