RESOLVE‐en.md

Here is an example of translation-sync instruction. Save this somewhere in your translation fork project and let AI handle the rest.

# Translation Sync & Auto-Resolution Guide

Our translation target language is: **Japanese**

This guide is designed to help AI agents (you) assist with the *translation sync process* used in the **React Official Documentation Translation Project**, which involves reflecting updates from the English source into the translated version.

The target branch already contains a **commit with conflict markers**. This is created when the latest changes from upstream (English version) are merged into the translation side, and the resulting conflicts are forcibly committed using `git commit -a` without resolution. Note that our workflow does not start from "mid-merge" state, but rather from a state where **conflict markers themselves are already committed**.

The files you will work on contain conflict markers like the following, **already committed**:

    <<<<<<< HEAD
    [Potentially outdated current translated content]
    =======
    [New content from upstream (English) side]
    >>>>>>> aa11bb22

Unlike the typical Git merge process (manual editing during conflict resolution), this procedure targets already-committed conflict markers. You must automatically fix them by referencing the pure change history from the English side while maintaining translation quality. The goal of this procedure is to **understand the updates in the English source, automatically fix the translation files, and remove the markers**.

## 0. Prerequisites & Terminology

* Sync branch: A branch named like `sync-aa11bb22`, which will be checked out at the start. The `aa11bb22` portion is the commit hash of the English version to sync with. The bot automatically creates these branches as follows:

    git checkout main
    git fetch upstream
    git checkout -b sync-$(git rev-parse --short upstream/main)
    git merge upstream/main
    git commit -a

* Translation fork: `origin` (Translated version of React documentation)
* Source remote: `upstream` (English version of React documentation)
* Current sync target (UPCOMMIT): `aa11bb22` (extracted from branch name; referred to below as environment variable `UPCOMMIT`)
* Previous sync point (BASE): The commit obtained via `git merge-base main "$UPCOMMIT"`, which indicates "how far upstream has been merged into main" (hereafter, referred to as `BASE`)

## 1. Initialization (Run Once at Start)

    # Get status and branch name
    git status

    # Update references
    git fetch upstream
    git fetch origin

    # UPCOMMIT = the upstream commit we're trying to merge this time
    UPCOMMIT=$(git rev-parse --abbrev-ref HEAD | sed 's/^sync-//')

    # BASE = the upstream commit that was already incorporated into the fork's main at the previous merge.
    # That is, common ancestor of main and UPCOMMIT = how far upstream has been merged into main
    BASE=$(git merge-base main "$UPCOMMIT")


## 2. List Files to Process (Files with Conflict Markers)

    git grep -l '^<<<<<<< \|^>>>>>>> '


## 3. Main Loop (Process Each File)

Process the files listed in Step 2 one by one. In short, this is a cycle of semantically reflecting the changes from BASE => UPCOMMIT into the OURS translation.

First, read the target file (e.g., `src/content/learn/tutorial.md`) and identify the sections containing conflict markers.

Next, retrieve the changes that occurred in the source English version.

    # Get the diff with line numbers (changes added to the English version since the last sync)
    git diff --no-color "$BASE" "$UPCOMMIT" -- src/content/learn/tutorial.md

* `$BASE` is the English version at the last sync point.
* `$UPCOMMIT` is the English version to sync with this time.
* In other words, this diff shows "what changed in the English version since the last sync."

Read this diff and **understand the changes that occurred on the English side**. Examples of changes:

* Typo fixes and minor corrections (spelling, punctuation, formatting changes)
* URL fixes (link destination changes, anchor changes)
* Content additions/deletions (adding or removing paragraphs or code blocks)
* Updates to code samples or heading structure

While reflecting the meaning of the English diff, update the currently checked-out translation file and remove the conflict markers. The resolution result should be **marker-free translated text that semantically reflects the changes in the English source**. In other words, you'll perform a translation-aware three-way merge.

* Use the **ours (translation)** content as a foundation, while ensuring that the English changes are semantically reflected (in the form of modifying existing translations or creating new translations). Refer to the full English text at UPCOMMIT or the git log from BASE => UPCOMMIT as needed.
* For simple typo fixes or minor corrections in the English version (such as space corrections), you don't need to change the translation. Just keep the ours side and remove the markers.
* When content is added or significantly rewritten in English, add corresponding translated text. Reuse existing translations when possible, but create new translations for completely new English text.
* If content has been deleted in English, also delete the corresponding translated text.
* After removing conflict markers, ensure that the correspondence between the source structure (paragraphs, section order) and the translation doesn't break.
* To avoid issues with future git diff detection, **strictly match line number correspondence** between the English version (at UPCOMMIT) and the translated version after marker removal, accurately mimicking the structure of the English version at UPCOMMIT (number of blank lines, line break positions, etc.).
  * The English Markdown may have unnatural structures like no blank lines immediately after headings or consecutive unnecessary blank lines, but preserve these exactly in the translation version; do not make arbitrary "corrections."
  * Don't split a single line of text in the English version into two lines in the translated version. Since the source has no line breaks within paragraphs or sentences, if there are N lines between `=======` and `>>>>>>>`, there should also be N lines after conflict resolution.
* Don't touch anything outside conflict sections. However, depending on how conflict markers are detected, you may need to edit outside markers to maintain structural integrity. In such cases, you may edit outside markers to preserve consistency.

## 4. Important Notes

* **Important**: Focus on accurately resolving **obvious** conflicts, and skip complex diffs. "Obvious" means that, by looking at a local conflict or 1-2 surrounding conflicts and their corresponding diffs, you can sufficiently determine what happened. For non-obvious cases, skip them and defer to human judgment.
  * For example, when content is rearranged in complex ways, many non-intuitive conflict markers may appear. In such cases, skip without forcing it.
* Also skip cases where files have been renamed or deleted in the English version, or for binary files.
* Don't touch auto-generated files like `yarn.lock` that are not suitable for manual conflict resolution.
* Do not commit, push, or run tests after processing. Consider the task complete once you've overwritten and saved the file
* Finally, report a summary of the edits you made to the chat as follows. Also report any skipped work.

    - ✅ `src/content/learn/setup.md`: Newly translated the added Expo section
    - ✅ `src/content/learn/state.md`: Link URL changes (5 locations)
    - ✅ `src/content/learn/tutorial.md`: English typo correction only, no translation changes
    - ❗ `src/content/reference/api.md`: Skipped entire file due to major section structure changes
    - ❗ `src/content/blog/index.md`: Resolved conflicts for obvious typo fixes only, skipped major rewrite section in the first half
    - ❗ `yarn.lock`: Skipped due to special file type