NEAR Wallet TRANSLATIONS.md // Guidelines discussion

[stefanopepe]

NEAR Wallet is available in English as the main language, with translations/localizations in Chinese, Russian, Portuguese and Vietnamese. These contributions are almost entirely done by the community, who spend time keeping track of the new releases to add their translations.
Localization is done by modifying JSON files located at https://github.com/near/near-wallet/tree/master/packages/frontend/src/translations. Each translation file begins with a two-letter country code (e.g. en for English, vi for Vietnamese) and contains a self-explanatory list of content and events that will be rendered by the wallet frontend.
Contributors can open pull requests to these files, making sure to use the translation label (see here for clear examples).

This process is unstructured and needs better guidelines for:

1. Informing/alerting these teams when a new release needs localization efforts
2. Updating the JSON files and evaluating the UI results (e.g. not too long labels)
3. Tracking the efforts (e.g. number of words, number of hours, frequency)
4. Compensate this work (e.g. bounty program)
5. Quality assurance and accountability

This discussion wants to collect feedback for concerns, requirements, risks - generally speaking, "what could go wrong" so we can anticipate and mitigate while introducing the minimum friction as possible.

I want to hear from the people who would work on:

• design
• development
• translation

As the PM, I'll release a document that will take care of community communications, bounty program design, and QA & accountability aspects, taking into account the feedback collected below.
We'll have four distinct phases:

1. Collect the concerns, avoiding pushback and comment on others' feedback - DEADLINE 12/8
2. Comment on the concerns from others - DEADLINE 12/12
3. I'll publish a high-level draft addressing these concerns - DEADLINE 12/16
4. Comment on the proposed LOCALIZATION.md file - DEADLINE 12/19

No worries: we'll anyway adopt the first release of the localization until the end of Q1 2021, and we'll review the process after some battle-testing.

Looking forward to seeing your comments 🤩

[crypto-credit]

Hi great to see this discussion.
I think it would be useful to add translation / localization in Italiano to the list.
I look forward to see further details in the document you are releasing.
I can offer to take responsibility for English to Italian translation.

[KriptoRaptor]

Hello there
I think it would be useful to add translation / localization in Turkish as well.
I am willing to take the responsibility but I will be needing help with coding it. Or just hand over the text and you take care of the rest 😄
#2271

[picturepan2]

Thanks. I contributed the multilingual features/dev and translations (mostly Chinese, sometimes missing English).

The current workflow is:

1. Do translations before major feature release of NEAR Wallet is ready to production.
2. Feature developers will add translations tag to the PR which needed translations and notify me incase I miss it.
3. I do translations for the changed/missing part.
4. Then review it completely myself in localhost and later testnet if it is deployed to testnet. Make hotfixes if needed.
5. Take some times to review in production and keep listening feedback from both NEAR China and community.

It is also possible to list these strings which needs translations as a table for other non-developer people to contribute. Then review them and merge into code.

[stefanopepe]

We are closing phase 1 of this discussion.

Before starting phase 2 (debate), I'm adding these high-level concerns and requirements:
a. localized content shouldn't overflow, overlap or overextend buttons, labels, and other UI components >> UX/UI integrity
b. translation efforts should be objectively measurable, counting words and time spent to complete the tasks >> Auditability
c. rewards are allocated on a quarterly basis, to simplify the operations and reduce the sheer volume of payments >> Operations
d. localizations should begin as soon as a new release is available on the master branch (and visible at https://wallet.staging.near.org) >> Simplify the coordination overhead
e. every localization effort should open a new issue, and link it to the pull request changing the files >> Avoid opening PRs without explanation
f. QA will be in the hands of our community, who may share positive or negative feedback on the translation quality >> Simplify meritocratic dynamics

On the budget side we have a few of options:

1. per word or per hour (quite common in the market)
2. per release (independently of the size)
3. quarterly grant, independent from the total volume

2 would drastically reduce the overhead
1 requires more time on your end to account for all the work done
3 requires more time on the Wallet end to account for the quality and potentially interrupt the grant

Let's take a few days to collect comments on all the ideas above, and we can proceed.

@crypto-credit good idea, I'd be happy to see Italian among the available alternatives
@KriptoRaptor same as the above, let's go with the Turskish as well
@picturepan2 I want to remove the need for a dedicated tag in the PRs: changes can be tracked from from the canonical English language file here.

[KriptoRaptor]

I'm totally fine with all of the above.
but still not clear with the format i should use while doing the translations.

what about this kind of a docx document of each page? and then we will (me and the some guys from Turkish Guild) double check it once you guys upload it before going to online?

[stefanopepe]

what about this kind of a docx document of each page? and then we will (me and the some guys from Turkish Guild) double check it once you guys upload it before going to online?

The expectation is that you use any tool you like to create the translation, as soon as the final content is submitted as an updated .json file in the folder https://github.com/near/near-wallet/tree/master/packages/frontend/src/translations
This way, the build tool can automatically render the new translation file on the wallet user interface, and you can check by yourself the quality of the rendered result.

Otherwise, we would have to allocate someone to do a massive copy/paste, and then get back to you asking if the final result is valid or not (and do back-and-forth for every error or adjustment needed). This wouldn't be efficient nor scalable

[KriptoRaptor]

what about this kind of a docx document of each page? and then we will (me and the some guys from Turkish Guild) double check it once you guys upload it before going to online?

The expectation is that you use any tool you like to create the translation, as soon as the final content is submitted as an updated .json file in the folder https://github.com/near/near-wallet/tree/master/packages/frontend/src/translations This way, the build tool can automatically render the new translation file on the wallet user interface, and you can check by yourself the quality of the rendered result.

Otherwise, we would have to allocate someone to do a massive copy/paste, and then get back to you asking if the final result is valid or not (and do back-and-forth for every error or adjustment needed). This wouldn't be efficient nor scalable

ok this sounds reasonable😄 , I ll figure that out .json format once I complete the translation 🧑‍💼

[stefanopepe]

Below a first draft of the guidelines. Feel free to comment/quote.
As mentioned, there's no reward scheme yet, I'm working to have more clear information and add a "step 7" to the list.

[stefanopepe]

NEAR Wallet - community translations guide

This document is created to facilitate translation efforts by the community. This activity will change the user interface buttons, labels and messages from English (the official language used by the core team) and other languages.

Ideally, translators make sure that someone who is not proficient in English can use the wallet in their native language. Translators can help also with the localization, alerting developers if the interface is not correctly rendering locale settings such as date formats, decimal separators or special characters.

General guidelines

NEAR Wallet is open source, so you can submit pull requests containing updates to the language file, getting recognition when your changes are merged to the Stable branch.

With the goal of simplifying coordination and avoid duplication of efforts, the NEAR Wallet team will merge translations that follow some simple best practices:

• Don't work in isolation, contacting other translators before beginning any activity of this kind
• Inform the team if you plan to be offline for some time, so translations don't fall behind
• Always proofread your contributions, and alert other translators if you found typos or errors
• Since you are modifying the codebase, specify when you couldn't test the new language file (see below)

Ok, I'm ready, how do I get started?

To get the best results, follow these few steps:

1. Contact the other translators

2. Subscribe to the repository and get notified

3. Open a new issue and begin the work

4. Submit a pull request with the updated translation

5. Run tests to visually check the quality of your work

6. Submit your quarterly reports

7. Contact other translators

There's a dedicated chat on Telegram (TBD) where you can join the conversation. Use it to either propose a new language or just contribute to existing ones. You can use this channel also if you need some help or you identify a bug.

2. Subscribe to the repository and get notified

You can subscribe to the NEAR Wallet repo and get notified for every new pull request. See the official Github page on managing subscriptions for more details. Alternatively, you can use third-party services such as Github File Watcher to receive an email every time a commit to the repository changes a very specific file.

3. Open a new issue and begin the work

Make sure to submit a new issue, informing the Wallet engineering team that you are working on the translation. Select the dedicated template (TBD) and make sure to check for any replies to it.

All translation files are located in the directory /[packages](https://github.com/near/near-wallet/tree/master/packages)/[frontend](https://github.com/near/near-wallet/tree/master/packages/frontend)/[src](https://github.com/near/near-wallet/tree/master/packages/frontend/src)/**translations**/ . All the content that can be translated is contained in the JSON file en.global.json and contains a list of nested "key:value" items. Make sure to have the same structure of the file, and translate only the "value".

This is an example of a component in the English language file en.global.json:

"create": {
            "checkingAvailablity": {
                "check": "Checking",
                "create": "Checking availability"
            },

This is the equivalent translated in the Portuguese file pt.global.json:

"create": {
            "checkingAvailablity": {
                "check": "Verificando",
                "create": "Verificando disponibilidade"
            },

Heads up! Since this is a JSON file that will get rendered by the frontend, pay particular attention to the structure of quotations ", colons :, curly brackets {} and commas ,.

4. Submit a pull request with the updated translation

Make sure that you begin your work from the master branch, since it's normally the final step before the release.

You will need basic familiarity with Git, e.g. how to create branches and open pull requests. If you feel intimidated by this level of technical work, feel free to ask for help in the translation channel on Telegram.

5. Run tests to visually check the quality of your work

Every pull request generates a temporary URL with a version of NEAR Wallet containing your changes.

As an example, if your pull request is the number 2345, an instance of the wallet (running on the TestNet network) will be available at the URL [https://near-wallet-pr-2345.onrender.com](https://near-wallet-pr-2345.onrender.com) . Make sure that all your changes are displaying correctly and don't break the user interface, translated content shouldn't overflow, overlap or overextend buttons, labels, and other UI components.

Take a few screenshots and add them to the issue at the step 3, as proof that your changes didn't break the UI.

6. Submit your quarterly reports

At the moment, NEAR doesn't have a formal retribution program for community translations, every work should be done on a voluntary basis, without expecting any form of payment.

However, NEAR Foundation and the community keep an eye on the most engaged members, including them in airdrops, bounties and other initiatives rewarding this type of commitment.

To report your work, make sure to keep track of:

• What is the "merge to master" event that changed the en.global.json file, as an example, see the release 2288.
• The issue you opened when you began the work (see step 3 above)
• The pull request that closed and merged your work, attesting that your translation is accepted

[stefanopepe]

(will do a grammar pass as soon as we completed the review)

[crypto-credit]

Hi @stefanopepe the NEARItalia community is growing! there is now an active Telegram Group and other community members have started work as a Guild. I am keen to push forward with the wallet translation into Italiano but have llittle experience using GitHub. Is there anyoone else that can help?

[stefanopepe]

Great news! Start with the json file as per instructions, then we can find someone from the other translators who's available to upload the file for you

[KriptoRaptor]

@stefanopepe we also have Turkish version ready. having hard time with github 😄
can we (@stefanopepe @crypto-credit and me) jump in a 30 min call and you (or any other developer friend you address) show us how to upload these translations correctly?

[crypto-credit]

Hi again! We have finally finished translating the wallet into Italiano! Who can help with the next steps?
I too am not a developer with experience of GitHub

[artem-p]

Hello there. Have you considered using services like transifex.com for translation? @stefanopepe