Documentation Edit - Add Notes to "How do I translate Refuge Restrooms.org?"

hnarasaki commented 5 years ago

Translating the Files Section:

Scope / difficulty

Easy/Minor documentation edit.

Impact

A user might miss this and translate something that should not be translated.

Proposal

On this page https://github.com/RefugeRestrooms/refugerestrooms/wiki/How-do-I-translate-Refuge-Restrooms.org%3F I would like to propose adding a note that if you see a value that is not in quotes, don't translate it.

Ex:

Do Translate: download-unisex-restroom-signs-hyperlink-label: 'I-download ang Mga Palatandaan ng Unisex na Silid' Don't Translate: public-api-hyperlink-label: Public API

Putting Files in the New Folder Section:

Would like to propose adding a note that you do not need to include "en.yml" file.

DeeDeeG commented 5 years ago

I think we can update that Wiki page, for sure. Thanks for the feedback.

I want to address the comments you have given here.

I would like to propose adding a note that if you see a value that is not in quotes, don't translate it.

Do Translate: download-unisex-restroom-signs-hyperlink-label: 'I-download ang Mga Palatandaan ng Unisex na Silid' Don't Translate: public-api-hyperlink-label: Public API

Actually if this phrase ("Public API") can be translated well into Filipino, that would be great! Of course, if it will make more sense without translation, that is fine also.

We should probably add quotes to the English translation file for this. (Public API --> 'Public API')

Would like to propose adding a note that you do not need to include "en.yml" file.

Yes, that makes sense. We intended the "en.yml" to be deleted, but it keeps showing up again. I will go and make sure it is actually deleted in our main branch. Hopefully we won't need a note not to translate that file, since it won't exist anymore!

In general, I think that guide could be somewhat improved now that we've accepted several languages and are more familiar with how it usually goes. We can add what has been learned since the page was originally written.

(A side note: I'm surprised you aren't showing as an official "Contributor" to this repository on GitHub. Since we have accepted commits that you authored, you should be officially a "Contributor". And we have set up the wiki so that all Contributors are be able to edit the wiki. I'm not sure what happened there. If you wanted to edit that page directly (and if GitHub would let you??) you would be welcome to do so.)

DeeDeeG commented 5 years ago

Here is an update on one of these points. I agree that the en.yml file is confusing at the moment. I moved it out of the en folder and renamed it to about_translations.yml

(I decided to keep the file in some form, since it has some interesting technical information about how the translations work.) See: #554

If other members of the team agree with this, or if they don't comment on it for a while, I will merge that change into our main branch.

I will also edit the wiki page with better instructions for translating Refuge Restrooms, once I figure out what exactly to write.

Best regards,

- DeeDeeG

DeeDeeG commented 5 years ago

Here's what I have so far:

The English translation files are finally sorted out, so now is a great time to translate!

Finding your locale code

The first step of translating Refuge Restrooms.org is to find out your locale code. This is a two-letter, or three-letter abbreviation for the language you want to translate. You can find this by searching "[language here] locale code", e.g. "Spanish locale code" in your search engine of choice.

(Some search engines: Google.com, Yahoo.com, Bing.com, DuckDuckGo.com, etc...).

Most locales we can use will be one of the following (from here)

af, ar, az, be, bg, bn, bs, ca, cs, cy, da, de, de-AT, de-CH, de-DE, el, el-CY, en, en-AU, en-CA, en-GB, en-IE, en-IN, en-NZ, en-US, en-ZA, en-CY,eo, es, es-419, es-AR, es-CL, es-CO, es-CR, es-EC, es-ES, es-MX, es-NI, es-PA, es-PE, es-US, es-VE, et, eu, fa, fi, fr, fr-CA, fr-CH, fr-FR, gl, he, hi, hi-IN, hr, hu, id, is, it, it-CH, ja, ka, km, kn, ko, lb, lo, lt, lv, mk, ml, mn, mr-IN, ms, nb, ne, nl, nn, or, pa, pl, pt, pt-BR, rm, ro, ru, sk, sl, sq, sr, sw, ta, th, tl, tr, tt, ug, ur, uz, vi, wo, zh-CN, zh-HK, zh-TW, zh-YUE

If your locale code is not listed there, it should be listed here or here.

Adding a folder for your locale

First, you may want to take a look at the existing translation folders for the site. They are in this sub-folder: config/locales.

Once you know the locale code for the language you are adding, you can make a new folder named after that locale code. (For example, to add a folder for Spanish, the locale is es, so you would add an es folder at config/locales/es.)

Putting files in the new folder

You can copy files from whichever existing language you are most comfortable with into your new folder. If you are comfortable with English, please copy the English files, since English is the original language that Refuge's text was written in.

So you would:

copy every file (filename.en.yml) from config/locales/en into --> config/locales/[new-locale]

Then for each file,

rename from filename.en.yml to filename.[new-locale-code].yml.
and change the top line of each file from en: -> [new-locale-code]:.

For example, English to French:

splash.en.yml -> splash.fr.yml
en: -> fr:

(The file "en.yml" does not need to be copied into the new folder, or translated. It only has one line and is not used by our app. It does have some interesting information explaining how the translations work. Feel free to read it if you are curious!)

Translating the files

Every line in these files is a "key" and "value" pair.

Each pair is formatted like this: key: "value"

The "key" is on the left of the :, and its "value" is on the right of the :. You don't need to translate the "key," only the "value."

For example, this is a translation for the key "hello", from English to Spanish:

hello: "Hello!" --> hello: "¡Hola!"

Single quotes (`'`) and double quotes (`"`)

If the language you are translating to uses apostrophes ('), this may give problems when translating. Here is how to understand and fix the problem:

Every 'value' in a key-value pair (for example: key: 'value') needs to have quotation marks around it. These quote marks can be single quote marks (for example: 'value'), or double quote marks (for example: "value"). Either style of quote acts the same. It is fine to use either one, or just keep the style that was there when you started translating.

There are two things to consider that make it a bit more complicated: 1) Apostrophes (') look the same as single quotes to the Refuge Restrooms server, and this can cause errors. So, if the 'value' being translated has apostrophes in it, the whole phrase should be surrounded by double quotes

"Here's some text that's full of apostrophes. It's surrounded by double quotes." 2) Some of our translated phrases have quote marks within the phrase itself. These should be surrounded with single quotes.
'This phrase uses "double quotes" and should be surrounded with single quotes'

As a result, mixing and matching single vs double quotes, and deciding which to use, can be a bit tricky. If you need to use both apostrophes (') and double quotes ("), you can tell the Refuge Restrooms server to treat either kind of quote mark as text by putting a backslash (\) in front of it. For example:

"Here\'s a phrase with both \'single quotes\' and \"double quotes\" together!"

If you have any trouble with this, please let us know and we will try to help figure it out.

Any other questions?

We are here to help if you have any questions. Please post an Issue or Pull Request with the translation you are trying to make, and leave your questions in a comment there. Or you can ask on Slack, if you like.

DeeDeeG commented 5 years ago

Actually, it appears that I was wrong, and translations in config/locales don't need to be surrounded by quotes.

Here are some examples in the official documentation without quotes:

from https://guides.rubyonrails.org/i18n.html#lazy-lookup :

en:
  books:
    create:
      success: Book created!

from https://guides.rubyonrails.org/i18n.html#using-safe-html-translations :

# config/locales/en.yml
en:
  welcome: <b>welcome!</b>
  hello_html: <b>hello!</b>
  title:
    html: <b>title!</b>

DeeDeeG commented 5 years ago

I removed the en.yml file from the config/locales/en/ folder.

It is moved to the base folder of config/locales/, and renamed to about_translations.yml

hnarasaki commented 5 years ago

@DeeDeeG Cool, thanks! Should this issue be closed?

DeeDeeG commented 5 years ago

Sure.

Might add something to the wiki later about quotation marks, if I can think of what would actually be helpful rather than unnecessary (or even accidentally confusing)... But for now we can close this. :+1:

RefugeRestrooms / refugerestrooms