Rails I18n Guide: please review

[Sven Fuchs]

Hey everybody,

with Karel's help the Rails I18n Guide is now in a condition so that
we can release it for the final review/feedback cycle.

http://guides.rails.info/i18n.html

Please have a look and provide your feedback :)

Thanks!

[Niels Ganser]

Sven,

the guide looks great! It should probably be looked over by a few
completely uninitiated people to find out if all is comprehensible
without any previous knowledge of I18n's workings but I found it to be
very clear and straightforward.

Two minor issues, which might have been intentional though: at the end
of chapter 3.1 as well as 3.2 you write "NOTE You need to restart the
server when you add new locale files." and "NOTE Right now you might
need to add some more date/time formats in order to make the I18n
backend work as expected. See the rails-i18n repository for starting
points." respectively. My guess is those notes should be displayed in
the little yellow box with the note icon next to it?

Also, in chapter 4.3 it might make sense to just list all plural
categories (zero, one, two, few, many, other) as very few people
inside the English speaking world are even aware of them.

Lastly, I find http://github.com/zargony/rails-i18n/tree/master
tremendously helpful to automatically pull in localisation files for
Rails core in my application's languages. My guess is that many
newcomers to i18n on rails start out highly motivated and then quickly
break down crying when they don't easily find localisations/
translations for everything Rails core in at least the major
languages. There are many references to the main rails-i18n repository
but I think they could be even more highlighted and maybe amended with
a mention of zargony's fork.

All in all only a few minor issues with an otherwise very helpful
guide though.

Thanks for writing it all up,
Niels

[Karel Minarik]

Hello Niels,

thank you for the feedback!, some of the issues you have mentioned
were fixed yesterday.

I also think "rails-i18n" should be more prominently placed in the
guide.

And of course, you're right about listing the pluralization options.

Some obvious things aside, I'd also like to put some guidance about
how to structure the dictionary files for nontrivial apps.

Thanks again!,

Karel

On Jan 22, 3:08 am, Niels Ganser <ni...@herimedia.com> wrote:
> Sven,
>
> the guide looks great! It should probably be looked over by a few
> completely uninitiated people to find out if all is comprehensible
> without any previous knowledge of I18n's workings but I found it to be
> very clear and straightforward.
>
> Two minor issues, which might have been intentional though: at the end
> of chapter 3.1 as well as 3.2 you write "NOTE You need to restart the
> server when you add new locale files." and "NOTE Right now you might
> need to add some more date/time formats in order to make the I18n
> backend work as expected. See the rails-i18n repository for starting
> points." respectively. My guess is those notes should be displayed in
> the little yellow box with the note icon next to it?
>
> Also, in chapter 4.3 it might make sense to just list all plural
> categories (zero, one, two, few, many, other) as very few people
> inside the English speaking world are even aware of them.
>

> Lastly, I findhttp://github.com/zargony/rails-i18n/tree/master

[Matt Falkenhagen]

Hello,

Thanks for this guide. I am just starting to develop an app with i18n
support so it is very useful to me.

I am quite new to both Rails (and Ruby) and i18n, so here is some
feedback from that point of view.

1. Move the paragraph in Chapter 3 defining internationalization vs.
localization to the top. The document starts hinting at the
difference from the beginning but doesn't make it explicit until
later.

2. The following sentence tripped me up:
"You probably want URLs look like this: www.example.com/en/books
versus www.example.com/nl/books."

I think it should read:
"www.example.com/en/books instead of www.example.com/books?lang=en"

3. This warning box is confusing:
"Following examples rely on having locales loaded into your
application available as an array of strings like ["en", "es", "gr"].
"

Set aside from the text like this, it gives the appearance that
nothing below it will work until Rails 2.3 (and does "following
examples" mean all the way until the end of the document?). It had me
wondering what I could do about it.

After some puzzlement, it seems like code sample below "We have to
include support for getting available locales manually in an
initializer like this:" is meant to define the available_locales
accessor mentioned in the warning box. I would make this connection
more clear. Maybe don't use a warning box and say "Therefore, we
manually define available_locales as follows."

4. I notice modern i18n websites like MSDN or Facebook include both a
country and language code in their URLs, e.g., en-us or ja-jp. I
assumed this is to distinguish between things like en-gb and en-us.
Yet the locale specification schemes presented in the guide include
only one code. As I am a beginner to i18n I don't fully understand
the issues here. It may be out of the scope of the guide, but maybe
some more information about this or links to other resources would be
helpful.

It seems easy to adapt the dual-code approach to everything except the
TLD-based locale selection. But in any case, won't basing locale on
the TLD cause trouble for countries where more than one language is
likely to be preferred?

5. There are many minor English issues that jumped out at me. Any
chance that this guide will be put on a wiki? They are too numerous
and too minor to list here.

Thanks again for the guide. It is the most useful resource I have
found for rails-i18n.

[Karel Minarik]

Hello Matt,

thank you for your feedback, good catches. Couple of these things were
bugging me as well, so I had one more reason to fix'em .)

> 1. Move the paragraph in Chapter 3 defining internationalization vs.
> localization to the top. The document starts hinting at the
> difference from the beginning but doesn't make it explicit until
> later.

Yes. This is due to the fact that I started messing with content
originally from Sven and didn't make the cuts on all proper places.
At least this issue should be fixed now.

> 2. The following sentence tripped me up:
> "You probably want URLs look like this:www.example.com/en/books
> versuswww.example.com/nl/books."

OK, I've tried to clarify this a bit more (http://github.com/lifo/
docrails/commit/aae0bec4f6db00435e833f76b244757caa9626b8)

> 3. This warning box is confusing:
> "Following examples rely on having locales loaded into your
> application available as an array of strings like ["en", "es", "gr"].

Good. I've tried to clarify that as well. I do think the box makes
sense cause people could skip it and *then* wonder why things are not
working.

> 4. I notice modern i18n websites like MSDN or Facebook include both a
> country and language code in their URLs, e.g., en-us or ja-jp. I
> assumed this is to distinguish between things like en-gb and en-us.

Great. This should be in the guide -- I've added an info box.

> 5. There are many minor English issues that jumped out at me. Any
> chance that this guide will be put on a wiki? They are too numerous
> and too minor to list here.

The best way would be to fork the "docrails" repository @ Github:
http://github.com/lifo/docrails/, make your changes and send pull
requests.

Let me know if today's fixups cover stuff you've mentioned.

Thanks,

Karel

[Matt Falkenhagen]

Hello Karel,

Thanks for your response. Yes your improvements do clear things up.

Regarding making changes, I'll try to get that set up sometime. I
haven't worked with GitHub or Git in general before.

Thanks,
Matt

[mh]

Although the beginning of section 4 Overview of the I18n API features
refers to: localizing dates, numbers, currency, etc., I was unable to
find any reference to or examples of numbers, currency, etc. other
than a single sentence fragment in 5.2.1 ActionView helper methods.
Would probably be worth at least an example each of formatting numbers
and currency.

Thanks.

Michael

[Karel Minarik]

Hi Michael,

do you think it needs more explanation? Because usually, you just drop
a (eg) `de.yml` file into your locales directory and you're set. The
guide would be very, very long if it should discuss every detail like
these.

However, some more instructional general info is probably still
needed.

Thanks,

Karel

[Erwin]

great .. but something still not clear enough ..
setting the locale .. should be string 'en' or sym :en ??

I18n.locale = params[:locale] is a string...
I18n.locale
"en"

I18n.locale = :en
:en
I18n.locale
:en

what should be used ?

[mh]

Hi Karel,

Two things about this:

1) Since I'm working on delivering numbers and dates in a localized
format but *outside* of a view, it strikes me as a hole in the i18n
API that the localize method that ships with Rails only works on Date/
Time objects.

2) Nevertheless, a one-line example of each one of these helper
methods would be useful, I think.

Thanks.

Michael

[Kip]

Looks good. Small suggestions:

1. In section 2.1, in the note, I think the example locale is better
to be :en-GB rather than :en-UK. Also, in that locale, the currency
symbol is £ not €.

2. This note I also find quite confusing. I says that the I18n
library only uses the language key, not the region key. But then
later on says you can use the region key if you want. It also
suggests inheriting from a locale - which as far as I know doesn't
make much sense (using inheritance in the Ruby class context which I
think most people would use as the context here).In fact, as far as I
can tell, I18n library places no restrictions on naming the locale at
all. I could call is :this_is_my_silly_locale if I wanted. I18n and
SimpleBackend don't care.

So at the risk of editing something I'm a novice at, may I suggest
something like (for the 2.1 note section):

------
Rails I18n (with the included SimpleBackend) doesn't impose any formal
structure or requirements on naming locales. I18n takes the pragmatic
approach and the only locale included in a default Rails installation
is :en (that is, the english language). Many international
applications use only the "language" element of a locale such
as :cz, :th or :es (for Czech, Thai and Spanish). However there are
also regional differences within different language groups that may be
important. For example, the currency symbol is different for the UK
versus the US even if both speak English. Therefore you might
consider creating a locale named :en-GB which is the same as the
default :en, but with the current symbol changed from $ to £. This
same approach can be used to adjust for different spellings, grammar
or date/time formats in different regions that use the same overall
language (like the differences between :de-DE, :de-AT, :de-CH).

Note that the SimpleBackend that ships with rails does not provide
locale fallback. That is, it will look for translation and
localisation data in the requested locale and only that locale.
Therefore if you are implementing multiple regional locales for a
common language (:en-GB, :en-US, :en-AU for example) you will need to
include the complete set of translations and localisations in each
locale file - even if they are a very close copy in most cases. There
are several plugins that do provide fallback mechanisms
(Globalize2, ...) and you may consider one of these for your
application.

------

Use or discard as you see fit,

Cheers, --Kip

[Karel Minarik]

Hi Kip,

I like your wording of this section quite a lot.

I'll put it in as soon as possible,

the pound issue is already fixed,

thanks!!,

Karel

[Karel Minarik]

Hello all,

I have put some fixes in:

* Fixed incorrect examples of ActiveRecord error message lookup in the
I18N guide [Thanks Alex Fortuna] [http://github.com/lifo/docrails/
commit/61656cf7702f46fcbb810a70bf0298ac5ea6c0d3]

* Added information about "lazy lookup" inside views (`t '.foo'`) in
I18N guide [http://github.com/lifo/docrails/commit/
a6f1e42c096a626b8a071094545d35f90d19ab55]

* Clarified info about "pragmatic approach to locale codes" and
removed speculation about "locale inheritance" in the I18N guide
[thanks Kip] [http://github.com/lifo/docrails/commit/
959b827e40248691864221d9d8561f17fb5755a6]

* Added information about "Localized views" into I18N guide [http://
github.com/lifo/docrails/commit/
92dd9b3e9f7bffe16ec53aeefd048d7da4eb1543]

* Added note how to configure Rails loading mechanism to look for
nested locale files (+config/locales/models/book/es.yml+, etc) to the
I18N guide [http://github.com/lifo/docrails/commit/
48d4c0f0116117e45fd268f9fa8ae502d7f15cc7]

* Get rid of drop shadows in screenshots for the I18N guide [http://
github.com/lifo/docrails/commit/
e1c0763e47f76b916324c5a062b50ede41a51e3c]

More feedback appreciated!

--karmi