diff --git a/AUTHORING.md b/AUTHORING.md deleted file mode 100644 index 17516b583..000000000 --- a/AUTHORING.md +++ /dev/null @@ -1,37 +0,0 @@ - -# Authoring - -This describes important stuff about authoring new articles of the tutorial. - -## Internal links - -All tutorial links should start from the root, not including the domain. - -✅ OK: - -```md -We'll cover that in the chapter [about functions](/function-basics) -``` - -❌ Not ok: - -```md -We'll cover that in the chapter [about functions](https://javascript.info/function-basics) -``` - -Also, to reference a chapter, there's a special "info:" scheme, like this: - -```md -We'll cover that in the chapter . -``` - -Becomes: -```html -We'll cover that in the chapter Function basics. -``` - -The title is auto-inserted from the referenced article. That has the benefit of keeping the right title if the article gets renamed. - -## TODO - -Ask @iliakan to for more details. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..d4ada5199 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contribuições + +Esse documento contém recomendações de como contribuir com traduções para o tutorial. + +## Passo a passo + +1. Abra a issue #1 +1. Escolha um artigo sem atribuição +1. Adicione um novo comentário na issue com o nome do artigo **exatamente** como está na lista +1. Crie um fork do repositório e traduza o conteúdo do artigo, isso inclui os exercícios +1. Abra um pull request com o título idêntico ao usado no comentário. + +> [!TIP] +> Segure a tecla Alt para selecionar o texto de um link sem acessar a página + +## Traduções + +Ao traduzir qualquer texto, mantenha algumas considerações em mente: + +**Uma tradução verbatim (literal, palavra por palavra) normalmente não auxilia no entendimento do conteúdo.** Lembre-se: Estamos contribuindo com um tutorial! O mais importante é oferecer um texto de fácil compreensão. Expressar os conceitos de maneira clara é mais importante do que uma correspondência exata ao texto original. + +**Evite usar serviços de tradução para trechos inteiros**. Se o trabalho de tradução fosse algo tão trivial quanto usar uma ferramenta automatizada, não teríamos todo esse trabalho, não é mesmo? Quando estiver com dificuldades para traduzir um trecho ou um termo, considere as seguintes alternativas: + +1. Qual a ideia que o texto apresenta? Tente expressar essa ideia usando suas próprias palavras (usando sempre do bom senso, claro). +1. Peça ajuda a outras pessoas! É um trabalho colaborativo no final das contas. +1. Talvez parte do texto seja uma expressão popular que não possui uma equivalência exata. Nesses casos a dica 1 é bem útil. Busque entender a expressão na língua original para realizar a tradução. +1. Ao invés de usar um serviço de tradução direta, procure o termo em alguma enciclopédia online na língua original, e mude a página para a sua língua de destino em seguida. Isso é bem útil para traduzir termos técnicos! + +> [!NOTE] +> Independente do que escolher, lembre-se que a recomendação é contra *trechos inteiros*. Nada impede você de usar esses serviços para traduzir um termo isolado, ou buscar sinônimos de uma tradução que você já conheça. + +**Gramática e concordância são importantes, mas não deixe que isso te impeça de contribuir!** É para isso que temos o processo de revisão em duas etapas. Duas pessoas diferentes vão revisar sua contribuição e sugerir mudanças antes de qualquer coisa ser integrada do projeto de fato. É uma ótima oportunidade para você aprender mais sobre as línguas também! + +**É um tutorial que te ensina JavaScript, não um documento oficial.** Repare que em diversos momentos do texto o próprio autor usa de expressões, maneirismos e passagens descontraídas. Claro, como mencionado acima, gramática é importante! Mas não precisamos usar uma linguagem tão formal - Priorize o entendimento! + +**E o mais importante, conte conosco!** Somos uma *comunidade* num esforço *coletivo* em benefício de *toda a comunidade lusófona*. Em caso de dúvidas, não exite em abrir uma issue. + +> [!CAUTION] +> Os artigos contam com uma sintaxe específica do tutorial para certos elementos: `pattern:`, `subject:`, `match:`, etc. Os termos antes do `:` não devem ser traduzidos. + +## Links internos + +Todos os links do tutorial devem ser relativos e começar da raiz, sem o domínio. + +✅ Correto: + +```md +Abordaremos isso no capítulo [sobre funções](/function-basics) +``` + +❌ Errado: + +```md +Abordaremos isso no capítulo [sobre funções](https://javascript.info/function-basics) +``` + +Além disso, para referenciar um capítulo, há uma sintaxe especial "info:": + +```md +Abordaremos isso no capítulo . +``` + +Que torna-se: + +```html +Abordaremos isso no capítulo Funções básicas. +``` + +O título é inserido automaticamente a partir do artigo referenciado. Isso tem a vantagem de manter o título correto se o artigo for renomeado. + +## TODO + +Pergunte a @iliakan para mais detalhes. diff --git a/README.md b/README.md index 371793d6d..62de0e670 100755 --- a/README.md +++ b/README.md @@ -1,38 +1,40 @@ -# The Modern JavaScript Tutorial +# O Tutorial Moderno de JavaScript -This repository hosts the English content of the Modern JavaScript Tutorial, published at [https://javascript.info](https://javascript.info). +Este repositório hospeda o conteúdo em português do Modern JavaScript Tutorial, publicado em [https://javascript.info](https://javascript.info). -## Translations +## Traduções -We'd like to make the tutorial available in many languages. Please help us to translate. +Gostaríamos de disponibilizar o tutorial em vários idiomas. Por favor, ajude-nos a traduzir. -See for the details. +Acesse para mais detalhes. -## Contributions +## Contribuições -We'd also like to collaborate on the tutorial with other people. +Também gostaríamos de colaborar no tutorial com outras pessoas. -Something's wrong? A topic is missing? Explain it to people, add it as PR 👏 +Algo está errado? Falta um tópico? Explique para as pessoas, adicione como PR 👏 -**You can edit the text in any editor.** The tutorial uses an enhanced "markdown" format, easy to grasp. And if you want to see how it looks on-site, there's a server to run the tutorial locally at . +**Você pode editar o texto em qualquer editor.** O tutorial usa um formato "markdown" aprimorado, fácil de entender. E se você quiser ver como fica no site, há um servidor para executar o tutorial localmente em . -The list of contributors is available at . +A lista de contribuidores está disponível em . -## Structure +Para saber como contribuir, leia o nosso [Guia de Contribuição](/CONTRIBUTING.md) -Every chapter, article, or task has its folder. +## Estrutura -The folder is named like `N-url`, where `N` is a number for the sorting purposes and `URL` is the URL part with the title of the material. +Cada capítulo, artigo ou tarefa tem sua pasta. -The type of the material is defined by the file inside the folder: +A pasta é nomeada como `N-url`, onde `N` é um número para fins de classificação e `URL` é a parte da URL com o título do material. - - `index.md` stands for a chapter - - `article.md` stands for an article - - `task.md` stands for a task (solution must be provided in `solution.md` file as well) +O tipo do material é definido pelo arquivo dentro da pasta: -Each of these files starts from the `# Main header`. + - `index.md` significa um capítulo + - `article.md` significa um artigo + - `task.md` representa uma tarefa (a solução também deve ser fornecida no arquivo `solution.md`) -It's very easy to add something new. +Cada um desses arquivos começa no `# Cabeçalho principal`. + +É muito fácil adicionar algo novo. --- ♥