This guide explains how to send your translations to the XWVM Localization repository using only your web browser. You don't need to install git or any other program to follow it.

The Forgejo screens may look slightly different depending on the Forgejo version and your browser language. The names of the buttons below are the usual ones. If something doesn't match exactly, look for the closest equivalent.

The big picture

1. You edit a file (or upload a finished one) in your own branch, which is just a separate copy of the work that belongs to you.
2. You open a pull request (PR), which is a request to the XWVM team to review your changes.
3. The team reviews it and merges it. Your translation is now part of XWVM.

Your changes never go straight into the main texts. Nothing you do can break the game until the team approves it, so don't be afraid to experiment.

Words you will see

These words come from version control, the system that keeps track of every change made to a project. Forgejo is the website that hosts it for us. You only need to know what each word means, not how it works inside.

Word	What it means	Everyday comparison
Repository (repo)	The project's folder on the website, with all its files and the full history of changes. Ours is xwvm-localization.	A shared folder that remembers every change ever made to it.
Branch	Your own separate copy of the files, where you can work without affecting anyone else. The official copy is called main.	Making a photocopy of a document to write your corrections on, instead of writing on the original.
Commit	Saving your changes into your branch, together with a short note saying what you did. Every commit is kept in the history, so it can always be undone.	Pressing Save and writing a note like "Spanish: fix X-wing names".
Commit message	That short note. One line is enough, for example Spanish: fix X-wing names.	The subject line of an email.
Pull request (PR)	A request to the XWVM team: "I made these changes in my branch, please review them and add them to the official files." The team can see exactly what changed, comment on it, or ask you for corrections.	Handing in your corrected copy for the editor to check.
Merge	When the team accepts your pull request, your changes are copied into the official files.	The editor copying your corrections into the original document.

In the screens below, "commit" is simply the button or step where you save your edit, and "create a pull request" is where you send it to the team for review.

Before you start

• Log in at git.xwvm.eu with the username the team gave you.
• Open the xwvm-localization repository.
• Find your locale code (es, pt-BR, ...) in Localization for Translators.
• Know where your files live:
  • CSV files: the CSV folder, with names like XWVM.xwing.Species_es.csv.
  • XLIFF files: XLIFF/<locale>/, with names like XWVM.Common.CombatVocab_es.xliff.
  • Fonts: the Fonts folder. Don't upload fonts on your own; ask the team first (see Providing fonts for a locale).

Which method should I use?

Method	Best for	Risk
A. Edit in the browser	A few corrections to a file that already exists.	Low for CSV. Medium for XLIFF, because one wrong character can break the whole file.
B. Edit locally, then upload the file	Translating many texts, or a whole new language. Recommended for XLIFF files.	Low. The tool checks your work for you.

Method A: edit a file in the browser

1. In the repository, click through the folders until you reach the file you want, and click its name.
2. Click the pencil icon (Edit file) above the file content.
3. Make your changes in the editor. Don't touch anything that isn't a translation (see CSV and XLIFF below).
4. Click the Preview Changes tab to see exactly which lines you changed. Check that only the lines you meant to change appear.
5. Scroll down to Commit Changes:
   • In the first box, write a short description, for example Spanish: fix X-wing names.
   • Choose Create a new branch for this commit and start a pull request.
   • Name the branch translation/<locale>-<your-name>, for example translation/es-maria.
6. Click Propose File Change.
7. On the next screen, click Create Pull Request. Give it a title such as Spanish translation update, optionally add a comment for the reviewers, and click Create Pull Request again.

That's all. The team will review it. You will get a notification if they ask for changes.

Editing more files in the same pull request

Don't create a new branch for every file. Instead:

1. Go back to the repository's main page.
2. In the branch selector (top left, it says main), choose your branch, translation/es-maria.
3. Edit the next file and, when committing, choose Commit directly to the translation/es-maria branch.

The pull request updates by itself.

Method B: edit locally and upload the finished file

This is the recommended method for XLIFF files, and for any big translation.

1. Download the file: open it in the repository and click Download (or Raw, then save the page with Ctrl+S).
2. Edit it on your computer:
   • XLIFF files: with Poedit, a free translation editor. See Translating with Poedit. It shows the original text and your translation side by side, marks the texts that are still untranslated, and writes the XML for you, including the special characters.
   • CSV files: with a text editor or a spreadsheet program, as explained in Translation of CSV files.
3. In the repository, go to the folder where the file lives.
4. Click Add file > Upload file.
5. Drag your edited file into the box, or click it to choose the file. The file name must be exactly the same as the original, otherwise you create a second file instead of replacing the first one. You can upload several files at once.
6. Under Commit Changes, write a short description, choose Create a new branch for this commit and start a pull request, name the branch (translation/es-maria), and click Propose File Change.
7. Click Create Pull Request, as in Method A.
8. Open the Files changed tab of the pull request. You should see your file as modified, with the lines you changed. If it shows the whole file as removed and added again, something changed in the file that you didn't mean to change, usually the line endings or the encoding. Tell the team in a comment on the pull request.

Editing CSV files

CSV files hold one value per column, separated by ;. The rules are explained in Translation of CSV files. The ones that matter most here:

• Never change the first line (the header) or the first column (the ID).
• Keep the same number of ; on every line. Example of a correct line, and the same line broken by a deleted ;:

  XWing;X-W;;X-wing;;;X-wings;;
  XWing;X-W;X-wing;;;X-wings;;
  

  The second line has one column fewer, so the game reads every value one column off.
• If your text contains a ;, wrap the whole value in double quotes: "Contenedor; Tipo A".
• If your text contains a double quote, double it inside a quoted value: "El ""Halcón""".
• Use the normal ;, not look-alike characters.
• Keep the file in UTF-8. The browser editor does this by itself. If you use Excel locally, export as CSV UTF-8, and check the result in a text editor afterwards, since some spreadsheet programs change the separator to , or damage accented characters.

Editing XLIFF files

XLIFF files are XML. The rules are explained in Translation of XLIFF files. In the browser editor, change only the text between <target> and </target>.

Before:

<unit id="CMD_SPD">
	<segment state="initial">
		<source>SPD</source>
		<target></target>
	</segment>
</unit>

After:

<unit id="CMD_SPD">
	<segment state="translated">
		<source>SPD</source>
		<target>VEL</target>
	</segment>
</unit>

Warning: special characters in XML

Because XLIFF is XML, three characters have a special meaning and can't be typed as they are inside <target>. One mistake makes the whole file unreadable, and the game will show missing translations for every text of that file, not just yours.

You want to write	You must type	Example
&	&	Ordenar & atacar
<	&lt;	Escudos &lt; 50%
>	&gt;	Velocidad &gt; 100

Also watch out for:

• Never delete a </target>, </source>, </segment> or </unit> closing tag, or the > at the end of a tag. Every opening tag needs its closing tag.
• Copy the { }, [[ ]] and (( )) markers from the original text, as explained in Translation of XLIFF files.
• Accents and special letters (ñ, ü, ç, я, 日) are fine. Type them directly. Don't write them as &...; codes.
• An empty <target></target> shows "Missing translation" in the game. If a text must be empty, write a single space.

Our advice: for XLIFF files, prefer Method B with Poedit. Poedit escapes the special characters for you, keeps the XML valid, shows which texts are still missing, and lets you work through the file from top to bottom. Then upload the resulting file, replacing the existing one. Editing XLIFF in the browser is fine for fixing a word or two, but for anything bigger it's easy to make a mistake nobody notices until the game is run.

Troubleshooting

I don't see the pencil icon, or the Edit file button is disabled. You may not be logged in, or you may not have write access yet. Log in, and if it still doesn't work, ask the team to check your permissions.

I don't see the option to create a new branch and start a pull request. Some Forgejo versions only show it after you write the commit message, or hide it if you don't have the right access. If you only see Commit directly to the main branch, don't use it. Ask the team to confirm your permissions.

I committed to main by mistake. Tell the team. It can be undone, and nothing is lost.

The pull request says "This branch has conflicts". Someone else changed the same file while you were working. Don't try to fix it. Write a comment on the pull request and the team will sort it out.

The Files changed tab shows the whole file as changed, not just my lines. Your editor changed the line endings or the encoding. Save the file as UTF-8 and keep the same line endings. If you can't fix it, tell the team in a comment.

I uploaded a file and it was added next to the original instead of replacing it. The file name was different (check capitals, the locale code and the extension). Delete the extra file from your branch, rename your file to exactly the original name, and upload it again.

The team says my XLIFF file is not valid. The cause is almost always an unescaped &, < or >, or a deleted closing tag. Look at the lines you changed in the Files changed tab, or open the file in Poedit, which will tell you if the file can't be read.

I need to change something after I opened the pull request. Switch to your branch (branch selector, top left), edit the file again, and commit to the same branch. The pull request updates itself.

I have more questions. Write a comment in your pull request, or contact the team.

Checklist before creating the pull request

• The file name is unchanged.
• I didn't change the header line, the IDs, the <source> texts or the XML structure.
• Preview Changes / Files changed shows only the lines I wanted to change.
• Special characters in XLIFF are escaped (&, <, >).
• The branch is named translation/<locale>-<my-name>.