Localize Final Fantasy XIV

How it works

Five steps take a line from the game back into the game, translated. Two repositories, a pull request and a plugin take part. No file of the game is modified.

Quick path

In the browser

Four clicks on GitHub. Nothing to install, no git to learn.

See the four steps → Full path

With a clone and an editor

Clone both repositories and translate in your editor, with the English, French and Japanese beside you.

See the four steps →

Quick path

In the browser

Everything happens on GitHub. The first click creates a fork of the repository, that is, your own copy. This is how anyone who does not own a project proposes changes to it.

1

Open the file on GitHub and press the pencil

Go to the language repository, into the corpus/ folder, and open the file of the conversation. The pencil at the top right opens the editor. If you are not a collaborator, GitHub first asks you to fork the repository. Accept.

ffxiv-language-pack-xx/ corpus / flat / DefaultTalk.json✎

●You need to fork this repository to propose changesFork this repository

The fork is created in a second and the editor opens on it. This happens only the first time.
To find a line, search its English text in ffxiv-corpus-en. The file has the same path in both repositories.

2

Write target

Write the translation in the target field of the row. Do not change gameKey or hash: they identify the line. Text between angle brackets is a macro; copy it as it is.

github.com · ffxiv-language-pack-xx · DefaultTalk.json

    { "gameKey": "DefaultTalk#590415.20", "hash": "E38048F1B03D2DD9", "target": "Sono il capitano a contratto dell'Orion." },
    { "gameKey": "DefaultTalk#590415.21", "hash": "5869006EA8C4FD7E", "target": "" },

You can change one row or a hundred, in one file or in several. The pull request carries them all.
The English, French and Japanese of the row are in the same file of ffxiv-corpus-en.

3

Commit changes, then Propose changes

Commit changes opens a dialog. Write a message that says what you translated; GitHub creates the branch in your fork. Propose changes leads to the pull request. Create pull request opens it against the language repository.

Propose changes

Commit messageAhldskyf, captain of the Orion

Branchpatch-1 → mainPropose changes

✔Able to merge. These branches can be automatically merged.Create pull request

The message must say which lines you translated. The release notes are generated from it.

4

Wait for the check

When the pull request exists, validate checks every changed row. If it is green, the pull request merges by itself. If the language has a reviewer, it waits for their approval. If it is red, the report says which row fails and why. Fix it in the same branch and the check runs again.

ffxiv-language-pack-xx· Pull request

✔validate checks every changed row: only target changed, the JSON is valid, the macros are in place and there are no placeholdersvalidate

●If the language has a reviewer, the merge waits for their approval. If it has none, it does not waitAuto-merge enabled

⛙Merged into main

The first pull request of a brand-new GitHub account waits for the maintainer to start the check. The next ones run on their own.

Full path

With a clone and an editor

The English is in one repository and your language in another. Both have the same files and the same lines. With both open in an editor, you translate with the French and the Japanese in view.

1

Open the two repositories

Open ffxiv-corpus-en and your language's repository in Visual Studio Code or another editor. Both have the same structure under corpus/: one file per conversation and one file per interface sheet.

Visual Studio Code

EXPLORER

▾ ffxiv-corpus-en

▾ corpus

▾ quest

▾ 041

AktKba101_04102.json

▾ ffxiv-language-pack-xx

▾ corpus

▾ quest

▾ 041

AktKba101_04102.json

ffxiv-language-pack-xx ›corpus / quest / 041 / AktKba101_04102.json

{
  "conversation": "quest/041/AktKba101_04102",
  "gameVersion": "2026.08.11.0000.0000",
  "entries": [
    { "gameKey": "quest/041/AktKba101_04102#TEXT_AKTKBA101_04102_SEQ_00", "hash": "6100EBD3346502DA", "target": "" },
    { "gameKey": "quest/041/AktKba101_04102#TEXT_AKTKBA101_04102_SEQ_01", "hash": "A91C0F3E6D2B7C10", "target": "" },
    …

Fork the language repository on GitHub and clone the fork. That is how you can push your branch.
ffxiv-corpus-en is read only. Clone it or browse it on GitHub. It is not edited.

2

Find the same file in both

The file path is the same in both repositories, and so is every gameKey. The English file has the line in English, French and Japanese. Yours has the same key, a hash and an empty target.

Visual Studio Code

ffxiv-corpus-en ›corpus / quest / 041 / AktKba101_04102.json

{
  "gameKey": "quest/041/AktKba101_04102#TEXT_AKTKBA101_04102_SEQ_02",
  "en": "The effort to find the blasphemy is being led by none other than the Elder Seedseer herself, Kan-E-Senna.",
  "macro": "The effort to find the blasphemy is being led by none other than the Elder Seedseer herself, Kan<-->E<-->Senna.",
  "fr": "Les recherches du blasphème sont menées par la Grande Prophétesse en personne, Kan-E-Senna.",
  "ja": "ブラスフェミーの捜索は、カヌ・エ・センナ様が自ら指揮を執っている。",
  "hash": "3C7D2A9E5B1F8E04"
}

ffxiv-language-pack-xx ›corpus / quest / 041 / AktKba101_04102.json

{
  "gameKey": "quest/041/AktKba101_04102#TEXT_AKTKBA101_04102_SEQ_02",
  "hash": "3C7D2A9E5B1F8E04",
  "target": ""
}

Split the editor: the English on one side and your file on the other.
When in doubt, search by gameKey. It is the value both files share.

3

Translate

Write the translation in target. Start from the English, the French or the Japanese, whichever you understand best. Text between angle brackets is a macro the game fills in when it shows the line: the player's name, a line break, a variant by gender. Copy the macros as they are.

Visual Studio Code

ffxiv-language-pack-xx ›corpus / quest / 041 / AktKba101_04102.json

{
  "gameKey": "quest/041/AktKba101_04102#TEXT_AKTKBA101_04102_SEQ_02",
  "hash": "3C7D2A9E5B1F8E04",
  "target": "La búsqueda de la blasfemia la dirige nada menos que la Gran Vidente en persona, Kan<-->E<-->Senna."
}

Save the file without changing its format: UTF-8 without BOM and the same indentation. An editor that understands JSON does this by itself.
A conversation is a file. Translate it whole so the voices stay consistent.

4

Commit, push, pull request

Create a branch in your fork. Make a commit with a message that says what you translated. Push the branch and open a pull request against the language repository. You can do this from the terminal or from the editor's git panel.

Terminal

$ git checkout -b ahldskyf
$ git commit -am "Ahldskyf, capitano dell'Orion"
$ git push -u origin ahldskyf
$ gh pr create --fill

Open one pull request per batch of lines, not per line. The release notes list its commits.
From here on, the process is the same as in the browser: the check, the merge and the release.

What is not touched

Four rules, valid on both paths. The check enforces the first three. The fourth makes the translation good.

gameKey · hash · gameVersionNot edited. They identify the line and its patch. The check rejects any change to them.
<--> <br> <if(…)>Copied as they are: the same ones the English has, not one more. An added macro breaks the line. A removed macro loses a name or a line break.
"target": ""Empty means untranslated. Do not write placeholders like TODO: the game would show them.
fr · jaRead them. The French shows how the line is said. The Japanese is the original and clarifies what it means.

After the pull request

Nobody intervenes. The check runs, the merge happens, the release is built, and the plugin offers it to every player at start.

ffxiv-language-pack-xx· Pull request → Release

✔validate checks every changed row: only target changed, the JSON is valid, the macros are in place and there are no placeholdersvalidate

●If the language has a reviewer, the merge waits for their approval. If it has none, it does not waitreview

⛙Merged into main

▲Release built and published. It takes two to three minutesrelease

◆Gubal Library offers the new version at start and shows your lineGubal Library

The Unending Codex in Spanish, showing Alphinaud's entry — **The Unending Codex**The Spanish pack translates the Codex entries about characters, places and concepts.

Quest dialogue in the game's own conversation window, translated — **What the player reads**The Spanish pack in the conversation window. Yours looks the same: the game draws your text with its own font, italics and colours.

The languages

One repository per language. The translated share is read from each repository when the page loads.

Language	Repository	Translated	Wrong line?
Español (España)	ffxiv-language-pack-es-es	—	issues
Italiano	ffxiv-language-pack-it	—	issues
Português (Brasil)	ffxiv-language-pack-pt-br	—	issues
Polski	ffxiv-language-pack-pl	—	issues

Another language? Ask on GitHub Discussions.