Frequently Asked Questions

What are localization files?

Localization files help website software know which text to put in the page. When the user selects a locale (e.g. clicks on 日本語 on the website), the code does the following actions:

1. Saves data of the users preferred language choice 'ja'
2. looks up the file with Japanese

What is JSON?

JSON stands for Java Script Object Notation

Read more here: https://en.wikipedia.org/wiki/JSON

Why do we use JSON?

It's because the data is structured in such a way so that a computer can understand it quickly. We are trying to add documentation and support to make it easier for you to contribute.

How are they named?

Inside the locales directory, you may see files with strange names like ja.json. This indicates the Japanese Locale and the file format is JSON. But why is it ja and not jp? This is because we are using locale codes rather than country codes. We use an international standard called ISO 639-1. This makes it easy to interface with other software systems and create a common understanding around the world.

How can I edit the localization files?

1. You can edit them directly in GitHub using the process described in the README
2. You can use a text editor of your choice, such as Atom. Please do not use Rich Text editors like Notepad or Word. 🙅🏻
3. (Optional) You could try using a tool like BabelEdit, though there is a learning curve for this tool and we're less experienced with it..

How should I create a new file?

1. Look up the locale code for the language you want to add here. It should be two or three characters. For example, the code for English is en and the code for Japanese is ja.

2. Visit https://github.com/ourjapanlife/findadoc-localization

3. Click "Add New File" and "Create File"

4. In the Filename input, add locales/[locale code].json replacing [locale code] with the code found in Step 1.

5. Copy the contents of en.json to the text area.

6. Add the translations following the process in the README.

7. Save your changes by scrolling down to "Commit new file" and selecting "Create a new branch for this commit and start a pull request." Enter a short description of the changes.

8. Enter more extended details of the changes on the "Open a Pull Request" page

9. Work with the reviewers to resolve any issues and get your translation merged in!

10. The developers will need to make some small edits to incorporate the new file into the website.

What if I want to report a problem or make a suggestion with localization?

Please fill out a new issue here: https://github.com/ourjapanlife/findadoc-localization/issues/new/choose

If you have a suggestion related to the Findadoc website, outside of localization, please file it here: https://github.com/ourjapanlife/findadoc-frontend/issues/new/choose

I am not technical and having challenges

Please reach out to us in the Slack Group #localization channel. We understand that the tooling is a work in progress and may be confusing, and feedback is welcome. We appreciate all our volunteers and want to make this process as easy as possible. Suggestions and improvements to the wiki are welcome!