As a user, I want to read the geniza project in my native language so it's easier to understand.

[rlskoeser]

testing notes

note - this issue is a companion to #36, but they address different issues and function differently. this issue covers all the text on the site that isn't actual "PGP data" - in other words, nothing that would come from the database.

you might encounter documentation (or people) that use the terms i18n and l10n. these are lazy ways of writing the long words "internationalization" and "localization", where the numbers mean how many letters you skipped in the middle of the word. the former refers to writing code that can be translated into multiple languages, while the latter refers to actually doing the translation ("localizing") that code into some particular language. for the PGP, the developers will be doing the i18n, but the l10n can be done by the project team.

as a user

1. visit the test site and you'll see a (very basic) homepage that tells you what language you're currently reading the PGP in.
2. you'll notice that the default is english; there's also now a /en/ appended to the URL to indicate this.
3. check out the list of professions in english and you'll see the transliterated profession names.
4. choose another language to read in using the dropdown at the top right, and click "Go." (these languages are configurable and we can choose as many or as few as we want).
5. you should now see the profession names change to reflect your choice, and the url suffix should also change to a language code (e.g. /he/ for hebrew). note though that the actual URLs will still be in english (e.g. /ar/people). let us know in a comment if this makes sense - it's possible to instead do /ar/اشخاص/ or /ar/ashas (idk if these are correct but you get the point).
6. go back to the homepage by clicking "home" in the top left, and you should see the text after "your language is" has also changed. once you pick a language, the website will "remember" it until you make another choice - including if you refresh, close the tab, close the browser, etc. you can remove the choice by clearing your cookies to default back to english, or just choose it from the dropdown.
7. note that the rest of the language on the homepage didn't change! to make that work, we have to do some extra work from the content editor's point of view.

as a content editor

1. have a look at the locale folder on github. you'll see three folders: ar, en, and he, corresponding to our three language options. each has a folder inside called LC_MESSAGES (this is a standard name that's required to use).
2. go ahead and click the folder until you see a file called django.po. this .po file (called a "message file") stores translations for each bit of text on the website that can be translated into multiple languages. if you have a look at the .po file for hebrew, you'll see starting on line 46 entries for all of the bits of text on the homepage ("Geniza multi-language testing", etc).
3. there's a lot going on here, so let's review the type of messages that you may see in this file. notes I added are in parentheses.

#. Translators: button on language chooser in navigation  (note left by the developer for the translator)
#: templates/base.html:33  (where in the code this bit of text is located)
msgctxt "choose this option"  (extra context for the translator, since "go" could be translated many ways)
msgid "go"    (what the original (untranslated) text reads)
msgstr ""       (the place where the translation goes)

#. Translators: subheading on homepage                               
#: templates/home.html:9                                                      
#, python-format   (indicates this bit of text contains python code)
msgid "Your language is: %(lang_name)s" ("lang_name" will be filled in later; we don't know what it is right now)
msgstr "" (the translation will include a placeholder for "lang_name")

4. time to add a translation! there are dedicated programs available for editing .po files, but the easiest way to test it right now is just to edit on github. click the "pencil" icon in the top right to edit it directly:

5. now you can fill in some of the msgstr fields with translations in whatever language's file you're editing. they don't need to be correct or "real" translations, but doing them in the correct language would be good.
6. when you're finished, scroll to the bottom and find "commit changes". fill in a commit message in the top box (something like "add arabic homepage translations") and if you're feeling fancy also add an extended description of what you did in the bottom box (not required).
7. make sure you click "create a new branch for this commit and start a pull request". this way, the developers will be notified of the changes and will have a chance to review everything before adding the code. it also helps prevent situations where two people edit the file at the same time and one person's changes "win" (unlikely, but possible). the name for your branch isn't important; something like "arabic-homepage-l10n"
8. you're done! you just localized something. comment with your thoughts/opinions about the process. if you want to try a fancier way, also check out poedit, which is one possible solution for doing lots of localization at once.

dev notes

Basic django app with some public interface and menus or site content to be translated

• add a super basic css framework/stylesheet for prototyping
• create the base/home template
• create a basic header or footer

[thatbudakguy]

a few notes on how this is going so far:

• django figures out what language to load a page in using the LocaleMiddleware, through a series of fallbacks:

1. It checks if there's a language prefix in the requested URL, e.g. http://google.com/en/
2. If not, it looks for a cookie it may have set previously when the user selected a language using a special view for this purpose.
3. If not, it checks if the request includes the Accept-Language header.
4. Finally, it uses the default LANGUAGE_CODE from settings.py.

• you can wrap a list of urls in your urls.py in i18n_patterns() (from django.conf.urls.i18n) to make them automatically prefixed with language codes based on the active language. we want to keep admin/ and the i18n/ urls outside of this, but most other URLs (including the homepage) can go inside it.
• the "set language" view mentioned above works by allowing POST requests to /i18n/setlang (by default), which then sets a cookie for the user to remember the language they selected. this can be combined with a simple form with a <select> that can be rendered on every page, so the user can quickly pick the language they want and then django will remember it.
• languages that you want to be selectable through the above method are defined as a list of (code, _(name)) tuples called LANGUAGES in settings.py. the language name is translated (the _ is a common alias of gettext()) so that it also appears in the target language. django appears to already know how to translate the language names into other languages; I didn't need to write translations for them.
• translating template content uses the two tags {% translate %} and {% blocktranslate %}. neither allow interpolation of variables, so you need to do things as below in order to e.g. access a property on an object:

{# Translators: description on a person's detail page #}
{% blocktranslate with name=person.name profession=person.profession %}
{{ name }} was a {{ profession }}.
{% endblocktranslate %}

• the Translators: note above is a special comment; any comments in templates or .py files that start with that prefix will be automatically transferred to the .po file where translations are written, so that the translator has extra context about where the translation will be used.
• running django-admin makemessages --all will generate the .po files for every string that has been marked using _ (gettext() or gettext_lazy()). you need to have a directory structure set up with a locale/code/LC_MESSAGES directory for each supported locale, in each app (including the parent geniza app). this command should only be run inside the geniza/ app directory, not the project root directory, otherwise it indiscriminately tries to translate things like manage.py and your virtual environment. you can control this, but the only way is passing a ton of flags on the command line, which is a pain. the same is true for django-admin compilemessages.
• the above is the reason why we store common templates like base.html inside the main app directory instead of in the project root - so that makemessages can see them when it's run from inside that directory. settings.py is configured to expect this.
• django's docs include examples of localizing URLs, so that instead of /ar/people/ you would have /ar/اشخاص/. however, i'm not sure if this is intended for RTL languages. I don't think i've seen it used much (even though unicode is supported in URLs). if we want to do this, it's easy - just a question of if we think it makes sense. edit a middle ground might be using a transliterated version in the URL, which I do see a lot on the chinese web - for example baidu xueshu (https://xueshu.baidu.com/) is roughly equivalent to google scholar (https://scholar.google.com/), where 学术 "science" -> xueshu

[mrustow]

Keep URL in English — simpler that way. The rest worked after we pulled Nick into the meeting and went to private browsing. Committing was scary, but then I felt a surge of Trumpian power.

[sluescher]

Can we just get rid of the "go" button? And have it change with the dropbox?

[thatbudakguy]

@sluescher most likely, yes! this was just the simplest way for me to make it work for testing.
@mrustow thx for confirming about the URLs; english is definitely easiest.

smash that red "close" button if you think it's done!

[sluescher]

I will smash it!