From 6c4867c76cedbee8b7f61c3d5ff678fa5ad6a99a Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 29 Apr 2025 20:45:41 +0000 Subject: [PATCH] codeberg-translate: describe direct push config option (#481) Weblate can also be configured to push directly to the Codeberg repo but that requires adding the `translate` user as a collaborator in the respective repo. Also use this opportunity to improve grammar/formulations. Closes: #324 Co-authored-by: Gusted Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/481 Reviewed-by: Gusted Co-authored-by: Alex Co-committed-by: Alex --- content/codeberg-translate/getting-started.md | 106 +++++++++++++----- 1 file changed, 81 insertions(+), 25 deletions(-) diff --git a/content/codeberg-translate/getting-started.md b/content/codeberg-translate/getting-started.md index c7c6f47..06831e6 100644 --- a/content/codeberg-translate/getting-started.md +++ b/content/codeberg-translate/getting-started.md @@ -5,49 +5,105 @@ eleventyNavigation: parent: CodebergTranslate --- -This article will guide you, how to integrate Weblate with Codeberg. +This article will guide you on how to integrate Weblate with Codeberg. ## Projects and Components -The first thing you might notice, is that Weblate has Projects and Components. A Component is something that can be translated e.g. a Software or a Documentation. A Project is a Collection of Components that belong to the same thing. -e.g. You have a Software and the corresponding Documentation. Both use different translation systems. So you add a Project for your Software and one Component for the Software itself and another one for the Documentation. -In simple cases you only need one Component in a Project. +The first thing you might notice, is that Weblate has _projects_ and +_components_. -## Create a new Project +A component is something that can be translated e.g. a software or a +documentation. A project is a collection of components that belong to the +same thing, e.g. you have a software and the corresponding documentation. So +you add a project for your software and one component for the software +itself and another one for the documentation. In simple cases you only need +one component in a project. -On [Codeberg Translate](https://translate.codeberg.org/) log in with your Codeberg Account. Now click on "+" and select "Add new translation project". -Now just enter some Metadata such as the Name, the URL slug (This is just the URL you find your projects. You project will live under the URL `https://translate.codeberg.org/projects/`), the Link to the Website (if you -don't have one, just use the URL of your Codeberg Repo) and some instructions, how this Project should be translated (can be empty). This are just Metadata. They have no meaning, when you connect to your Codeberg Repo later. -Click on "Save" and you are done. +## Create a new project -## Add a Component +On [Codeberg Translate](https://translate.codeberg.org/) log in with your +Codeberg account. Now click on "+" and select "Add new translation project". +Now just enter some metadata such as the name, the URL slug (your project +will live under the URL `https://translate.codeberg.org/projects/`), the link to the website (if you don't have one, just use the URL of +your Codeberg repo) and some instructions, how this project should be +translated (can be empty). This are just metadata. They have no meaning, +when you connect to your Codeberg repo later. Click on "Save" and you are +done. -You now see your new project with no components at all. Now let's add a Component. +## Add a component -1. First click on the "Add new translation component" Button. You should see this Page. +You now see your new project with no components at all. Now let's add a +component. + +1. First click on the "Add new translation component" Button. You should see + this page. Image the add component page 2. Now enter the following: -- Name: The Name of your Component. You can choose freely. -- URL slug: The URL, you can find your Component (`https://translate.codeberg.org/projects//`) -- Source language: If the source language of your Project is not English, select it here. -- Source code repository: The URL to your Codeberg Repo e.g. `https://codeberg.org/Codeberg/Documentation`. If you already have a component, that uses this Repo, use `weblate:///` to link it with the existing component instead. +- Name: The name of your component. You can choose freely. +- URL slug: The URL, you can find your component + (`https://translate.codeberg.org/projects//`) +- Source language: If the source language of your project is not English, + select it here. +- Source code repository: The URL to your Codeberg repo + e.g. `https://codeberg.org/Codeberg/Documentation`. If you already have a + component, that uses this repo, use `weblate:///` to + link it with the existing component instead. -Leave the rest as it is and click "Continue". Weblate will now scan your Repo and you should see something like this: +Leave the rest as it is and click "Continue". Weblate will now scan your +repo and you should see something like this: Image the add component page -Weblate have searched your Repo for common translation structures and presents you what was found. If you select one, Weblate will set some settings automatically. You can change them later or fully configure -the component manually. Please note, that one Component only works with one translation system in one directory. If you have multiple, you need to add multiple components. +Weblate has searched your repo for common translation structures and +presents to you what it has found. If you select one of the suggested +structures, Weblate will set some settings automatically. You can change +them later or fully configure the component manually (visit [Manual +component configuration][mcc] for more details). Please note, that one +component only works with one translation system in one directory. If you +have multiple, you need to add multiple components. -1. On the following page, you should select "Gitea pull request" under "Version control system", so Weblate will create a new PR to submit changes to your Repo. If you haven't selected a Configuration from Weblate, visit [Manual Component configuration](/codeberg-translate/manual-component-configuration). Now you should just select a Translation License and click "Save". Now you are done on the Weblate side. - -2. On the Codeberg side, open your Repo settings and go the Webhooks. Now click "Add Webhook" and select "Gitea" from the drop down. Under "Target URL" enter `https://translate.codeberg.org/hooks/gitea` and click "Add Webhook". Now Codeberg will notify Weblate about changes in your Repo, so it will be automatically updated. - -Now you can share to the Link to Weblate to your translators. +[mcc]: /codeberg-translate/manual-component-configuration ## Commit translations to Codeberg -To commit the translations from your Component to Codeberg, go to your Component>Manage>Repository Maintenance and click on "Push" +After setting up a component of your project in Weblate, you have to +configure how Weblate should interact with your underlying repository to +feed the translations to it. The following two options are the most common +ones: + +1. If you want to proceed such that Weblate will open Pull Requests + with translations to your repository, you should select "Gitea + pull request" under "Version control system". + +2. Alternatively, you can setup Weblate to push translations directly into + your repo by selecting "Git" under "Version Control". Set the "Repository + push URL" to the SSH URL of your git repo (`git@codeberg.org:/.git`) and (optionally) specify the branch Weblate + should push to under "Push branch". For Weblate to be able to push + directly to your repo, you must add the `translate` user as a + collaborator in your Codeberg repo under "Settings > Collaborators". + +To finalize the Weblate setup, select a translation license and click +"Save". + +Now, your Codeberg repo might change while your translators are +working on the translations via Weblate. To make sure that your +Weblate repo is in sync with the Codeberg one, open your repo settings +in Codeberg and go the Webhooks. Now click "Add Webhook" and select +"Gitea" from the drop down. Under "Target URL" enter +`https://translate.codeberg.org/hooks/gitea` and click "Add +Webhook". Now Codeberg will notify Weblate about changes in your repo, +so it will be automatically updated. + +At last you can share the link to your Weblate project with all your +translators. + +By default, Weblate will periodically (24h) create a PR or commit directly +to your Codeberg repo. To commit the translations from your Component to +Codeberg manually, go to your Component > "Manage" > "Repository +Maintenance" and click on "Push".