Spanish translations for Intro to Open Source Course

[adiati98]

Based on this comment, Spanish translations will be part of Community Translations.

Let's discuss everything about it here, such as the process, the pain points, ideas, anything you want to share! ✨
I'll document everything so we can help other translations as well! 🙌🏽

[adiati98]

@samucodesh Here are some thoughts to get you started:

• [Optional]: You can rename your forked repo to make it clear that it contains Spanish translations. For example: YOUR-USERNAME / intro-spanish.

• By default, you can let folks directly access and learn on your forked repo.

  You can host it yourself if you'd like to have a sort of website. I think you can host pretty much everything on GitHub Page (and it's free!) or you can take a look at Netlify. Currently, we're using docsify for this project. You can read their docs about how to deploy it.

• Once you're ready, you can list your forked repo in the community-translations.md. Use the link to the Spanish README of Intro to Open Source Course so folks can go directly to the homepage of the Spanish translations.

[samucodesh]

Hi @adiati98 ,

Following our previous conversation about enhancing collaboration for the Spanish translations, I wanted to share some updates on my initial efforts.

I've taken the following steps:

• GitHub Pages: currently I deployed my translation on GitHub pages and is ready for feedback.
• Mentoring New Contributors: I've started reaching out to potential Spanish translators and offering guidance on getting started with the project.
• Contribution Guidelines: I've extended the contribution guidelines to include specific information for Spanish translators, making the process clearer and more accessible.

I'm excited about the initial progress, but I believe we can continue to improve collaboration and ensure the project's scalability.

I'm particularly interested in exploring the following ideas further:

• Dedicated Discord Channel: Creating a dedicated Discord channel for Spanish translators would be a fantastic way to enhance real-time communication, share resources, and foster community engagement. A dedicated Discord channel could also serve as a central hub for organizing regular community calls and facilitating a structured mentorship program.

I'd love to discuss these ideas further with you and explore ways to implement them effectively. I believe that by working together, we can create a vibrant and thriving Spanish translation community for the Intro to Open Source Course and Becoming a Maintainer Course.

[adiati98]

Hey @samucodesh,

These initial steps are fantastic! I really love that you also take mentoring new contributors into consideration. We really appreciate it! Thank you! ✨

Questions

I have some questions:

• What are your thoughts on adding "Empezar" to the navbar? I'm asking because clicking "Spanish" from the "Language" dropdown will take folks to the Spanish README.
• From which branch do you deploy the website? I can't find it anywhere.
• How did you deploy the website to the GitHub Pages? Did you use the directions from the link I gave you, or do you have any other resources? I need this for documentation purposes.
• I've read your extended contributing guidelines (or README?). Are these guidelines for Becoming a Maintainer Course? Sorry, I'm confused here. 😅

Brainstorm

I have some thoughts here. What I want to emphasize is although we understand that we need to slightly adapt some things based on the needs of the translations, we want all translations to reflect the original course's repo.

I would love @BekahHW to chime in, but she will be able to do that later, as OpenSauced will have a launch week starting tomorrow. However, I am dropping them here now to gain your perspective.

NOTE: Below things are just some of my ideas that still need to go through Bekah. She might have some other thoughts here. 🙂

Dedicated Branch for Spanish Translations

You might want to have a dedicated branch for the Spanish translations in your forked repo. This branch will be where folks push their translation contributions and where you deploy the website on GH Pages.

That way, you can still use the main branch to update the English version and pull the latest update from the main branch to update the Spanish branch. Do you have thoughts on this? Or is this what you're currently doing?

Contributing Guidelines

As for the extended contributing guidelines, of course, it would be great if you have guidelines that work best with how you want folks to contribute to your forked repo. You are the maintainer of the forked repo. So, you need to develop guidelines that can help you maintain the repo. 💙

One of the ideas that I have is to create a contributing folder in the translations/es folder like what GitHub Docs repo has. This folder will contain:

1. A README (in Spanish) that contains this information:

   • A link to the CONTRIBUTING file for folks who want to contribute to any OpenSauced course in the upstream repo (English version).
   • A link to the Spanish CONTRIBUTING file for folks who want to contribute to your forked repo.

2. Spanish translated CONTRIBUTING file with the same name: CONTRIBUTING.md.

3. A new file may be called contributing-spanish.md or contributing-es.md, where you can create guidelines for contributing to your forked repo. It would be helpful to have consistency in the file naming here throughout translations so we can easily point them out in the documentation.

So, the structure would be something like this:

.
└── translations/
    └── es/
        ├── README.md
        ├── contributing/
        │   ├── README.md
        │   ├── CONTRIBUTING.md
        │   └── contributing-es.md
        ├── chapter-1.md
        └── chapter-2.md

Once it's finalized, I can include this in the translating documentation so that folks can locate the contributing guidelines of the forked repos.

Dedicated Discord Channel

@BekahHW is the best person to answer this. So, I'll leave this to her. 🙂

[samucodesh]

Hi @adiati98

Questions

What are your thoughts on adding "Empezar" to the navbar? I'm asking because clicking "Spanish" from the "Language" dropdown will take folks to the Spanish README.

currently there is a similar behavior when referencing the es/ directory (only when the project is built)

From which branch do you deploy the website? I can't find it anywhere.

Branch estranslations (the same branch with which I made the PR)

How did you deploy the website to the GitHub Pages? Did you use the directions from the link I gave you, or do you have any other resources? I need this for documentation purposes.

1. I currently use GitHub Pages for personal use, which means I already have samucodesh.github.io reserved. All other projects can be found by adding / and the repository name

example 1 https://samucodesh.github.io/intro
example 2 https://samucodesh.github.io/New-Relic-Monitoring-Project-

2. I made an "automatic" deployment with github pages and actions from the repository functionality

I've read your extended contributing guidelines (or README?). Are these guidelines for Becoming a Maintainer Course? Sorry, I'm confused here.

Currently the extended contribution is aimed at two people, @a-ridley and @samucodesh , but the idea is to make it the standard for both courses, intro and becoming.

Conclusion: I'm updating intro, while collaborating with @a-ridley translate the new course

Dedicated Branch for Spanish Translations

Currently I have the main branch blocked, I use the esintrooss branch as a draft branch (This is where I resolve most bugs before committing and pushing to the estranslations branch). The main branch of the translations is estranslations and it is the one I have deployed in pages, the other branches are features branches

Do you recommend making this clear in the README for contributions from my forked repository?

Contributing Guidelines

I agree with this. Which means I have to move the files I already have to the new folder and update the references to the README file in Spanish, CONTRIBUTING in English and Spanish

1. A README (in Spanish) that contains this information:

To do (Done 50% (OpenSauced Contributing file en))

2. Spanish translated CONTRIBUTING file with the same name: CONTRIBUTING.md.

Done

3. A new file may be called contributing-spanish.md or contributing-es.md, where you can create guidelines for contributing to your forked repo. It would be helpful to have consistency in the file naming here throughout translations so we can easily point them out in the documentation.

To do (Done partially?)

[adiati98]

Hi @samucodesh,

Thanks for the update! Here are the following response:

Empezar

What are your thoughts on adding "Empezar" to the navbar? I'm asking because clicking "Spanish" from the "Language" dropdown will take folks to the Spanish README.

currently there is a similar behavior when referencing the es/ directory (only when the project is built)

I don't quite catch you here. What kind of similar behavior? If the behavior is the same, would adding "Empezar" be necessary?

GitHub Page

Can you confirm my understanding to deploy projects on GitHub Pages here?

1. Set up GitHub Pages for user.
2. Make an "automatic" deployment with GitHub Pages and actions.

Questions

• Do we have to set up GitHub Pages for user or can we do this without it? Like, by setting one for each project.

• Can you walk me through or give me resources to make automactic deployment with GitHub Pages and actions?

• With the automatic deployment, do we still need to set up GitHub Pages for the project from the settings as in screenshot below?

  

Contributing Guidelines

Heads up:

• I submitted a PR to add a README to the root. Besides as a homepage for the intro repo, this README will allow you (forked repos) to add a link to your contributing guidelines (to contribute to your forked repo) in the "Contributing" section.
• I submitted an issue to propose moving the CONTRIBUTING.md and i18n-guidelines.md to the root. I've explained the reasons in the issue, but for community translations, I imagine this will make it easier to add the forked repos contributing guidelines file to the root of the project.

I'm now thinking to not have a README for the contributing file as what GitHub docs have for simplicty matter. We can put all guidelines files in one place and link them to the README that's located in the root.

That said, let's hold this for now.

But you can start to draft your own contributing guidelines. We want you to have full control on how folks contribute to your forked repo. 😊

Just a note: All contributing guidelines in your forked repo should be in Spanish. 😉

Dedicated Branch for Spanish Translations

Awesome that you already have the dedicated branch! 🎉

Branch Protected Rules

I heard about branch protected rules a lot, but I'm honestly not too familiar with how it works. 😅

In my understanding, it's to protect a branch from being deleted or forced push. You can read this docs for further info on how to work with one.

Here is another resource for branch protected rules.

estranslations Branch

As this branch is where you merge in and deploy the Spanish translations, you might want to make this your forked repo default branch instead of main. You can read how to change default branch in this docs. So, when folks create a PR, it will be merged into this branch instead of main.

If it's possible to have multiple branch protected rules, it would be best to apply the rules on main and estranslations branches.

Do you recommend making this clear in the README for contributions from my forked repository?

If you change this as your default branch, I don't think you need to do that. However, it would be helpful to share this information to ensure that folks are comparing their branch with the right base branch when they create a PR.

Here is an example:

In the example, when I'm about to create a PR I see the base:main and compare:adiati98-patch-10. By default, the base branch will be the default branch. In this case, the default branch is main. So, I want to merge adiati98-patch-10 to the main branch.

You can add information with something like, "You want to make sure that the base branch is estranslations before creating a PR."

[samucodesh]

Empezar

would adding "Empezar" be necessary?

I would say that it is not necessary to add "Empezar" because the navbar already serves that purpose

I delegate the making of this decision to you.

GitHub Pages

Every time you push to the branch you have configured in the deployment, a GitHub action will be created that will implement the new changes.

Questions

Do we have to set up GitHub Pages for user or can we do this without it? Like, by setting one for each project.

I don't really understand what you want to do here. Give me a little more detailed explanation

Can you walk me through or give me resources to make automactic deployment with GitHub Pages and actions?

Step 1

Create a public repository with this name: adiati98.github.io

Step 2

Create an empty file or one with content (the file must be a .md or .html file), add it to git with git add, and then push it to the remote repository with git push

Step 3

Go to “settings”, “pages” and configure the deployment to take your main branch and /(root)

Step 4

Save changes

Step 5

After 2 minutes, go to another repository with static files, like the intro repository, do the same thing you just did in adiati98.github.io , but instead of choosing / (root), you are going to choose docs/

Note

If you need more help setting up GitHub pages, you can ask for it

With the automatic deployment, do we still need to set up GitHub Pages for the project from the settings as in screenshot below?

Yes, it is necessary to make that configuration with each individual repository that you want to deploy to GitHub pages

Branch Protected Rules and estranslations Branch

It seems perfect to me to make the decision to protect the estranslations branch, but I feel that it is not necessary to make estranslations as the default branch.

You can add information with something like, "You want to make sure that the base branch is estranslations before creating a PR."

It seems good to me, and I think that to make it easier to understand, I am going to add a screenshot and some extra steps to configure the PR correctly

[samucodesh]

Hi @adiati98

Analyzing the latest PR I realized that it is no longer necessary to deploy from the docs directory. again you will do it from / and choose the branch you are working on. You can copy the link of the deployment and put it in the link of the description of your repository

[adiati98]

Hey @samucodesh,

Thanks for walking me through the process of creating GitHub Pages! 💙

Responding to you:

1. Empezar. It's best for the translations to follow the original website's structure. That said, let's remove the "Empezar" and use the "Languages/Spanish".

2. Default branch. You can do whatever you think best. 🙂

3. Analyzing the feat: add a README and move LICENSE file to the root #207 I realized that it is no longer necessary to deploy from the docs directory.

   Both English and translations projects will always be deployed from the docs directory. The README on the root is only for the repo's info and won't be rendered on the website. Without this README, when you visit the intro repo, by default, you will be welcomed with the README from the docs.

   We're adding the README on the root with below reasons:

   • To make it consistence throughout OpenSauced repos, where we have info about the repo and OpenSauced logo.

   • To allow forked repos adding the link to their repos' contributing guidelines as the last list in the "Contributing" section as below example:

     We encourage you to contribute to OpenSauced! All contributors are required to abide by our [Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md).
     
     - For information on how to contribute to the intro repository, check out the [Contributing Guidelines](./docs/CONTRIBUTING.md).
     
     - To translate our Intro to Open Source or Becoming a Maintainer course, check out our [🌐 i18n Guidelines](./docs/i18n-guidelines.md).
     
     - For information on how to contribute to this translations repository, check out the [repo's contributing guidelines](<link to the forked repo's contributing guidelines>)

[adiati98]

Hey @samucodesh

I don't really understand what you want to do here. Give me a little more detailed explanation.

I mean, do we have to first set up the repo for the GitHub Pages that gives us the GitHub domain name as in USERNAME.github.io?

Or can we just deploy the project by setting the deployment for each project without having to set up the repo for GitHub domain name?

For example, on Netlify, we can just deploy a project without setting up anything for the URL. Then, Netlify will give a random URL name.

[samucodesh]

Hi @adiati98

I mean, do we have to first set up the repo for the GitHub Pages that gives us the GitHub domain name as in USERNAME.github.io?

That's right, if you don't, you won't be able to deploy your other repositories with GitHub Pages.

[adiati98]

Hey @samucodesh,

I've had a discussion with @BekahHW regarding to the community translations. And we came up with these:

• The forked repos that hold translations for our course would be 100% for translations.
• You only need to add the link to our English website in your forked repo. So, when folks click this link, it will take them to our website.

So, I think what you can do here:

• Remove all English and French files and folders from the branch where you deploy the translations project to and replace the with the Spanish translations.
• In the navbar, under "Languages", add link to our course on our website under "English". For example: https://intro.opensauced.pizza/#/intro-to-oss/README.

Please let me know if you have questions or need help! Thanks! ✨

[adiati98]

I took a look at the website. The link to the website in "Language" on navbar is exactly what we want! Thanks! 💙

Below are my findings and thoughts:

1. The images on the sidebar are broken as per screenshot.

   

2. The first line on Intro to OSS course sidebar is different with the English version.

   English

   

   Spanish

   

3. It's a good idea to replace the README on the root with the Spanish translations. However, please give information in the beginning with something like, "This repository is one of community translations of Open Source Education Path with OpenSauced." You can put it as a note so it won't be missed.

4. Because you forked repo will be 100% in Spanish, it'd be helpful to have "Language" on the each navbar and include the link to the website just like what you did with the Intro to OSS Course. That said, to the homepage https://intro.opensauced.pizza/#/README and to the Becoming a Maintainer course https://intro.opensauced.pizza/#/becoming-a-maintainer/README.

5. I see that you haven't started with the Becoming to Maintainers course translation. Again, as your forked repo will hold everything in Spanish, let's direct folks to the official website when they want to do this course. Maybe something like this:

   • Remove the content and leave the title

   • Remove the sidebar's content and leave the logo

   • Say on the page, "The translations for this course is a work in progress. Head to the official Becoming a Maintainer Course to take this course. If you'd like to help with the translation, please..."

     You can add here how you'd like your potential contributors to contact you if they want to help. It can either open a discussion (link to the discussion board of your forked repo), an issue, or any other methods that you prefer!

6. A question. Do you still want to keep the "Empezar"?

[samucodesh]

Hello @adiati98

The images on the sidebar are broken as per screenshot.

I think it's because it's also broken in the _sidebar.md file

The first line on Intro to OSS course sidebar is different with the English version.

Well. I understand, I'm going to change it to "Introducción al Open Source"

A question. Do you still want to keep the "Empezar"?

I'm going to delete it because I think it's useless.

[samucodesh]

It's a good idea to replace the README on the root with the Spanish translations. However, please give information in the beginning with something like, "This repository is one of community translations of Open Source Education Path with OpenSauced." You can put it as a note so it won't be missed.

Are you suggesting that I translate the README file?

[samucodesh]

Because you forked repo will be 100% in Spanish, it'd be helpful to have "Language" on the each navbar and include the link to the website just like what you did with the Intro to OSS Course. That said, to the homepage https://intro.opensauced.pizza/#/README and to the Becoming a Maintainer course https://intro.opensauced.pizza/#/becoming-a-maintainer/README.

OK

I see that you haven't started with the Becoming to Maintainers course translation. Again, as your forked repo will hold everything in Spanish, let's direct folks to the official website when they want to do this course. Maybe something like this:

Remove the content and leave the title

Remove the sidebar's content and leave the logo

Say on the page, "The translations for this course is a work in progress. Head to the official Becoming a Maintainer Course to take this course. If you'd like to help with the translation, please..."

You can add here how you'd like your potential contributors to contact you if they want to help. It can either open a discussion (link to the discussion board of your forked repo), an issue, or any other methods that you prefer!

I think there may be conflicts every time the branch is synced.

Isn't it better to continue using the course/translations/languages ​​structure?

[adiati98]

Hey @samucodesh

I'm not on my computer anymore and currently on my mobile app.
So, I will take a look closer at these and respond to you tomorrow.

FYI, I opened a PR to update the translations guidelines. You might want to check on it and let me know what you think.

Thanks 😊

[adiati98]

Hey @samucodesh,

I want to give you heads up.
We will soon migrate from docsify to Docusaurus as per PR #222.

[samucodesh]

Hey @adiati98

Thank you very much for letting me know in advance about these changes. I will be attentive to this update.