# Monthly localization engineering tasks for docs site (2026-03) Every month, after the technical writing team runs [their cleanup](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/tasks.md?plain=1) in `/doc`, the localization team should follow up with these tasks to keep `/doc-locale` in sync. These tasks ensure translation repos stay aligned with source content and prevent build failures. ## Setup First, ensure you have: * All localization projects cloned locally * The latest changes from `/doc` main branch * Access to run the `docs-i18n-lint` pipeline ## Expired redirects After the TW team removes redirects from `/doc`, we need to mirror these deletions in `/doc-locale`. Check the `docs-i18n-lint` job for failures - these indicate files that exist in `/doc-locale` but not in `/doc`. Usage: ```shell # Review the failed paths from docs-i18n-lint # Remove corresponding files from each locale directory rm /doc-locale/ja-jp/path/to/deleted/file.md rm /doc-locale/fr-fr/path/to/deleted/file.md # etc for all locales ``` ## Redirects component The Redirects component contains a list of all the Redirects files. This allows the GitLab Localization team to distinguish those files in Argo when deciding which ones to translate in the Asset Dashboard. The list of Redirects changes, so this list of files must be updated routinely. 1. Download the `list_redirects.sh` file from https://gitlab.com/gitlab-com/localization/docs-site-localization/-/snippets/4896711 2. If you are downloading this for the very first time, make sure you give execution rights ```shell chmod +x list_redirects.sh ``` 3. Run the file, with the path to the locally cloned forked repo as the first argument * Use the location of the forked project and not the upstream production as the `main-translation` branch is only available in the fork. * Here's an example of how to run the script with the path as first parameter: ```shell ./list_redirects.sh /.../..../.../localization/docs/prod-fork/omnibus-gitlab ``` 4. The output at the end should say something like "Exported results to .../list_files.txt". Open that file. * In the event there are no Redirects found, you instead can use a fake path that should never match any file. * See different output [scenario below](#redirect-output-scneario) 5. Open the `argo_translation.yml` file for the specified repo in GitLab 6. Copy the contents under `= IGNORED PATHS =` and replace the Technical Documentation component's `ignored_paths` under "Redirects" 7. Copy the contents under `= NEW PATHS FOR COMPONENT =` and replace all the `paths` for the "Redirects" component 8. Create an MR that merges the changes ### Redirect output scneario In this process, you may encounter one of the following five scenarios: | Scenario | Next Steps | |----------|------------| | Already existing content for redirects and the script has generated a new list of files | Replace the redirect content as outlined [here](#redirects-component) and update the date (sample [Merge Request](https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/prod/gitlab-chart/-/merge_requests/45)). | | Already existing content for redirects but the script generated zero file(s) | Remove all of the existing content from redirects as outlined [here](#redirects-component) and update the date (sample [Merge Request](https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/prod/gitlab-operator/-/merge_requests/37)). | | Already existing content for redirects and the script has generated the exact same list of files | No content change necessary, keep the old date as a reference and add a new updated date if necessary (sample [Merge Request](https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/prod/omnibus-gitlab/-/merge_requests/37/)). | | No existing content for redirects and the script has generated a new list of files | Add the content as outlined [here](#redirects-component) and update the date. | | No existing content for redirects but the script has no files | There's nothing to do as of now and no date needs to be added. | ## Localized GitLab University course links (Japanese) **Context:** Our translation system doesn't preserve custom URLs when source files are re-translated. When we manually change a link to point to its localized version, that change gets overwritten the next time the file goes through translation. This requires us to manually restore the localized link after such re-translation cycle. **Current scope:** Japanese University course links where localized versions exist (e.g., `gitlab-with-git-essentials-s2-jp`). Currently only one course requires this update, but if additional localized courses are created, or more custom URLs need to be managed (for example, marketing site URLs), add them to this list. **File:** `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc-locale/ja-jp/tutorials/gitlab_navigation.md` **Steps:** Update the University course link to point to the Japanese version: ```markdown # Change from: https://university.gitlab.com/courses/gitlab-with-git-essentials-s2 # To: https://university.gitlab.com/courses/gitlab-with-git-essentials-s2-jp ``` ## Sync validation After cleanup, run these checks: 1. Ensure `docs hugo_build` passes (confirms no broken redirects) 2. Verify `docs-i18n-lint` passes (confirms sync with `/doc`) 3. Check that English fallback is working for any missing translations