readme

Author: iliakan

README.md

@@ -1,19 +1,34 @@
-# The Modern JavaScript Tutorial in Portuguese (Brazil)
+# The Modern JavaScript Tutorial in Portuguese
 
-This repository hosts the translation of <https://javascript.info> in Portuguese (Brazil).
+This repository hosts the translation of <https://javascript.info> in Portuguese.
 
-Please help us to make the translation better.
+Articles can be in both Brazilian and European Portuguese. Translators are encouraged to write in a way that both regions understand. 
 
-- See the [Portuguese (Brazil) Translate Progress](https://github.com/javascript-tutorial/pt-BR.javascript.info/issues/1) issue.
+**That's how you can contribute:**
+
+- See the [Portuguese Translate Progress](https://github.com/javascript-tutorial/pt.javascript.info/issues/1) issue.
 - Choose an unchecked article you'd like to translate.
-- Add a comment to that issue to inform the maintainer that you're translating it.
+- Add a comment with the article title to the issue, e.g. `An Introduction to JavaScript`.
+    - Our bot will mark it in the issue, for everyone to know that you're translating it.
+    - The comment should only contain the title.
 - Fork the repository, translate and send a PR when done.
+    - PR title should match article title, the bot will write it's number into the issue.
+
+If you're a maintainer, you can just translate and push, but please check articles as translated in the [issue](https://github.com/javascript-tutorial/pt.javascript.info/issues/1), for others to see that.
+
+If you're just a newcomer, without write access to the repo, please kindly allow maintainers to review and merge your translation.
+   
+If something's unclear, feel free to ask, make an issue [here](https://github.com/javascript-tutorial/pt.javascript.info/issues/new) or in the [English repo](https://github.com/javascript-tutorial/en.javascript.info/issues/new). 
+    
+**Let others know what you're translating, in message boards or chats in your language. Invite them to join!**
 
 🎉 Thank you!
 
 Your name and the contribution size will appear in the "About project" page when the translation gets published.
 
-P.S. The full list of languages can be found at <https://github.com/javascript-tutorial/translate>.
+If you'd like to join as a maintainer, write us at <https://github.com/javascript-tutorial/en.javascript.info/issues/new>.
+
+P.S. The full list of languages can be found at <https://javascript.info/translate>.
 
 ## Structure
 
@@ -33,9 +48,15 @@ Additional resources and examples for the article or the task, are also in the s
 
 ## Translation Tips
 
-- The translation doesn't have to be word-by-word precise. It should be technically correct and explain well.
-- If you see that the English version can be improved – great, please send a PR to it.
-- Please keep line breaks and paragraphs "as is": makes it easy to merge future changes from the English version into the translation. 
+Please keep line breaks and paragraphs "as is": don't add newlines and don't remove existing ones. Makes it easy to merge future changes from the English version into the translation. 
+
+If you see that the English version can be improved – great, please send a PR to it.
+
+### Terms
+
+- Some specification terms are not to be translated, e.g. "Function Declaration" can be left "as is".
+- For other terms like `resolved promise`, `slash`, `regexp`, and so on look a good glossary, hopefully there's one for your language already.
+    - If there's no dictionary, look for translations in manuals, such as [MDN](https://developer.mozilla.org/en-US/).
 
 ### Text in Code Blocks
 
@@ -86,13 +107,35 @@ Example:
 [JavaScript](https://es.wikipedia.org/wiki/JavaScript) es un lenguaje de programación.
 ```
 
-For links to MDN, that are only partially translated, also use the language-specific version.
+For links to MDN, a partially translated version is ok.
 
 If a linked article has no translated version, leave the link "as is".
 
+### Metadata
+
+Some files, usually tasks, have YAML metadata at the top, delimited by `---`:
+
+```md
+importance: 5
+
+---
+...
+```
+
+Please don't translate "importance" (and other top metadata).
+
+### Anchors
+
+Some headers have `[#anchor]` at the end, e.g.
+
+```md
+## Spread operator [#spread-operator]
+```
+
+Please don't translate or remove the `[#...]` part, it's for URL anchors.
 
 ## Running locally
 
-You can run the tutorial locally, to immediately see the changes on-site.
+You can run the tutorial server locally to see how the translation looks.
 
-The server is at <https://github.com/javascript-tutorial/server>. 
+The server and install instructions are at <https://github.com/javascript-tutorial/server>.