chore: review and update `guide/best-practices`

[nazarepiedady]

This issue is to track the review process of all files inside the src/guide/scaling-up folder.

The objective of this review is to ensure that the grammar, language, and writing style of Portuguese are equally accessible for both Non-Brazillian and Brazillian. The plan is to use the orthographic agreement used in Brazil for most of the words and a few specific words will be used in the form they are used out of Brazil, we list some of the word translation examples that are obligatory:

• file must be always translated to the Portuguese word ficheiro, but the word could be documento.
• section must be always translated to the Portuguese word seção.
• typing, depending on the context must be translated to tipos, tipificando, tipificação, or tipagem.
• the verb to type, when it refers to the act of assigning a type to a variable or object, must be translated to tipificar, when not, must be translated to digitar.
• store must be translated to memória when the word is used in the state management context.

It is not possible to list all recommendations so the rest will be suggested in the pull requests.

Files:

• [ ] #138
• [ ] #139
• [x] #140
• [x] #141

We must make efforts to avoid foreignisation in the process of translation.

[viniciusdeliz]

@nazarepiedady why the comments were deleted?

[nazarepiedady]

@viniciusdeliz, The comments were hidden because they didn't add anything to the discussion and the Portuguese used in the documentation has evolved since then.

I realised that Portuguese speakers with a limited command of dictionaries and vocabulary won't be able to offer much help in translating or developing content that aims to serve Portuguese speakers without being exclusive.

However, all opinions on the ease and difficulty of understanding the content are always welcome.

And although I avoid exclusivism in translation, I prefer to use Brazilian Portuguese most of the time because I understand the limited knowledge of the language on the part of our Brazilian programming brothers and sisters.

[viniciusdeliz]

@nazarepiedady the comments were not hidden, they were deleted. Honestly I have never ever saw that happening in any open-source and collaborative project before. That's just flabbergasting.

Again, as I had included detailedly in other responses here that were silenced, and obviously oppressed, this is not about the capacity of readers using the dictionary or not. And it's problematic for you to say that Brazilians have limitations on the language. Can you just imagine this same scenario in the other way? Brazilian or Portuguese people saying that Angola people have limitations and problems on reading the dictionary?

I've mentioned it a few times, and will do it again since the content is not published anymore: I do believe and aim to collaborate in an unified Portuguese manner, not in Brazilian Portuguese or any other variation as a standard. This follows the basic premise of Acordo Ortográfico de 1990.

This is all very sad and disappointing @nazarepiedady. I've expected much more from you and your initiative. It seems that you're taking the translation as your project somehow. And all the Portuguese speakers involved with Vue are getting affected by this. Numerous times I've tried to stand by your side and vision and tried to understand your behavior and motivations, but this is just making the documentation outdated and frightening possible collaborators. The lack of participation from the user base in this project comes as no surprise.

@Jinjiang @skirtles-code can you guys have a look at this and give an opinion if it's normal and expected? Please consider the former Portuguese team, which had a much more lively, adaptable and open-to-debate repo with the former Vue3 VuePress docs. There were plenty of debates so far on this repo and its workflow, but I'll link here just one on the current published Portuguese translation: https://github.com/vuejs-br/docs-next/issues/292

I'll be ready to provide meaningful information and insights on this matter if necessary, and to clarify any matter that I've possibly failed to communicate. Again, I'm just trying to make the documentation as clear and as accessible as possible.

[nazarepiedady]

@viniciusdeliz, You don't have to complain on a full stomach, and you don't have to write a lot when you don't have anything valuable to say. I'll ask you a few questions.

How many countries speak Portuguese?

And how often do you read or hear anything in Portuguese that isn't Brazilian?

Do you have enough experience with non-Brazilian Portuguese?

And if you don't have enough experience with any other variation of Portuguese, why do you think you're qualified to produce content for all speakers of the language?

Portuguese content on all platforms is dominated by Brazilians.

How often do you see a non-Brazilian complaining about Brazilian translations?

All non-Brazilians have learnt to deal with the Brazilian way of speaking and writing Portuguese, because it's the second most popular variation behind the Portuguese they speak in their own countries. That's why a non-Brazilian's knowledge of Portuguese vocabulary and dictionaries is superior to that of a Brazilian, because the average Brazilian is usually only aware of and knowledgeable about Brazilian Portuguese.

I'll continue translating the content into Portuguese, preferring the Brazilian variation for 90% of the content and the general variation made up of words from the dictionary of all variations for the remaining 10%.

Those who complain simply don't want to learn; if someone has difficulties, they look for solutions; if you don't know the meaning of a word, you look it up in the dictionary.

My work is more for those who don't have the command of English to deal with dense material such as documentation, because those who already know English don't need this material as much.

This fruitless debate is being repeated a lot.

The material relies on the mastery of the Portuguese language on the part of its readers, programming is not a matter for the illiterate.

It's very difficult for a studious non-Brazilian not to turn to the dictionary every time they read or hear words in Brazilian Portuguese with which they are unfamiliar (this is when they don't learn the meaning of such words from their real-world referents).

Brazilians also have the freedom and possibility to do the same with all the Portuguese they read and hear.

[nazarepiedady]

@viniciusdeliz, I've been talking to Brazilian programmers for more than 8 years, I've helped several Portuguese speakers (Brazilian and non-Brazilian) and English speakers to start their careers in programming, as well as moderating and administering Brazilian (founded by Brazilians) and Portuguese groups on Facebook.

And you're the only one who's bothered by the fact that there's official material in Portuguese that isn't run by Brazilians.

[Jinjiang]

Folks, please cool down.

I'm obviously not a Portuguese language expert. I can't jump into this discussion directly and help you solve it. However, in terms of the methodology, or let's say the open source way, I'd like to share my limited experiences:

1. I never delete or hide comments. I don't think it's the effective way to maintain or drive the community. Even I thought some issues already done or meaningless, I just reply to them with necessary explanations, which I think, aligns with as many as possible people on the same page in a peace manner. Sometimes, I closed the whole issue. But if I realized I was wrong at first, I can still re-opened it.
2. If I feel some discussions are really important but lack "valuable" input. I would try to call the whole language community for more voices. The more voices you have introduced, the more likely you get sufficient input from both sides and have an open and convincing result.
3. I never judge people by acting/knowing anything or not. I discuss with people based on facts and my own personal feelings about the facts. Most of the times, it's constructive and efficient.
4. For every single conclusion/alignment, I would arrange them into a wiki page as a guideline. And the guideline will also include links to the original discussion place. So people can always refer to the full discussion history to understand it.

At last, I'm open on any other ways we run this we think good enough. Hopefully it helps. ❤️

[nazarepiedady]

@Jinjiang, You also know me from translation initiatives for other tools in the Vue ecosystem, I rarely hear or read complaints about the translations I do, although they admit they're not usual.

I know the people in charge of the Brazilian Portuguese translation of the Vue.js version 2 documentation, and none of them have come out against the current translation.

However, there is a small group whose only discernible annoyance is that the official Portuguese version is now not authored in Brazil, even though the documentation is in Portuguese.

I've been slowly organising the repository, because at first it was a rush job due to the short time I had, but now I'm making the necessary updates as quickly as possible whenever they occur in the official documentation.

I recommend that you don't get involved, because as you can read from my comments, it is possible to make use of the current documentation with minimal effort.

Studying and researching is what we do most as programmers, so it's not something out of the ordinary to have to do the same when it comes to material like documentation.

[nazarepiedady]

@Jinjiang, As for the hidden comments, they don't add anything.

The most obvious thing is that the complaining parties are bothered by the fact that the variation of Portuguese used is not entirely Brazilian, and Brazil is just one of more than 6 Portuguese-speaking countries.

I try to cater for as many speakers as possible from the different Portuguese-speaking countries, and leave the rest to the efforts of each person interested in the content of this version, because we mustn't forget that there is the official English version that they can use if they know English.

But I'll find out if there's any way of reversing the action and showing the comments again.

And I'll also close this issue because the documents mentioned have already been updated.