Okay, wow, this mod is SO COOL and your community would be so happy to discover it! Or your coplayer MUST add it so you can play it together!... Thing is, your mate isn't as comfortable with English as you, or they just like to play in their native language. Or you just like to translate things. Well, here is a tutorial to help you – not to translate (it's your job!), but to do all the things around.

This tutorial is a more practical, step-by-step, "get your hands dirty" guide than the Translations page of the official Stardew Valley Wiki. As such, they are complementary. Moreover, this page quotes directly the official one in a few places (because writing the same thing but a bit less well would be stupid).

Choosing a mod

One may be slightly overwhelmed by the sheer number of mods deserving a translation! For your first experience, pick one you’ve played with and that isn’t too big. Mods adding objects and mods adding dialogues are fairly different, you might want to choose the type with which you feel the most comfortable.

Let's start with some tips. First and foremost: READ THE MOD DESCRIPTION. This might save you time in following the next steps because the modder would have already detailed how they’d prefer their mod to be translated.

Secondly: ASK THE MODDER. They will answer most of the questions you may ask yourself.

Choose a mod that works. 1.6 compatibility: Stardew Valley 1.6 was released on the 19^th of March 2024. Look at the “Last updated” date: this is a good indication. Some modders may have tagged their mod as well.

Stable mod: Look for signs that the mod is stable. Do you play with it without issues? Were there a lot of updates recently? Have players been reporting issues recently?

You may want to let the modder polish their work before starting anything.

Choose a mod that hasn’t been translated in your language yet. It doesn’t take much time to verify if the mod has already been or not translated into your language.

Look if the flag corresponding to the “Translations” submenu in the “Description” page is present (not every language has got one!)
Take a look in the mod files. You don’t need to download it: go to the “Files” tab and click on “Preview files content”. If there’s a i18n folder in which is a file named “[your language’s prefix].json”, the mod is translated.
Check the description. But you already did it, didn’t you.

Note: Some long existing mods may have translations that are obsolete or missing elements. A new translation may be welcome! Contact the modder to ask them.

Choose a mod with internationalisation (i18n) Preserve the coding and the hair on your head.

Internationalisation, or i18n, allows modders to “externalise” the in-game text in a separate file where every language has got its own file. Huge plus:

Everything that must be translated is in the same place
No risk to mess with the code
You don't have to upload the entire mod, just the translation file (modders have the right to forbid the reupload of their original work)
Core mod and translation are independent. This allows players to update the mod without having to wait for the new version of the translation.

ASK THE MODDER. (Skip this step if the modder said permission is not needed for translation. But you already read the description, didn’t you.)

If you need reasons, here are some:

The modder will be happy.
If you have some questions later, the modder will welcome them.
Somebody might already be translating the mod in your language, having asked permission.
The modder is going to translate their mod themselves.
The modder is working on a major update that would make your work obsolete (but they may be able to give you the files to translate ahead of time!).
The modder doesn’t want a translation.
That’s basic politeness.

Translating

The mod is stable and up to date, the mod creator gave their blessing and the i18n file is present! But how do you look at what's inside?

Software

The .json file on which you’re going to work is a text file. You could very well use Notepad on Windows or TextEdit on Mac (just change the .json with .txt), but there are several free and open source software that will make your work far easier with features like sync scrolling and colour-indication.

Here are some open-source softwares:

Windows:

NotePad++: Notepad++ is a free (as in “free speech” and also as in “free beer”) source code editor and Notepad replacement that supports several languages. Running in the MS Windows environment, its use is governed by GNU General Public License. from the official Notepad++ website Don't look farther than that if you're on Windows!

Mac:

BBEdit: BBEdit is the leading professional HTML and text editor for macOS. [It] has been crafted to serve the needs of writers, Web authors and software developers, and provides an abundance of features for editing, searching, and manipulation of prose, source code, and textual data. from the official website Its free version is perfectly adequate fot what you'll do.

(please complete) Pulsar ? Phoenix Code ?

Linux: (please complete)

Content of an i18n file

AKA the "What the heck am I looking at" section.

An i18n file basically contains text that looks like this:

{
   "translation-key-1": "Translatable text",
}

The first part (before :) is the unique key for the translation. This is how the mod identifies the translation, so you shouldn't change it. The second part (after :) is the text you're going to translate.

Do not touch the { and }.

Translation keys

The keys are determined by the mod creator in the mod code. When the game “reads” the mod and comes across a key in the code, it will find the i18n folder, choose the language file in which you set your game up and display the text attached to said key.

The vast majority of modders are organised people. Actually, they don't have much choice, as they would be themselves lost in their own work if they don't make a clear key system. That's why you're going to find the same key system accross most of the mods.

NPC dialogue: An NPC (including the vanilla ones) has got a fairly straightforward organisation: one line for each day of the week, changing each time you gain two more hearts with them - reflecting your friendship's evolution. Marriageable candidates have got another full layer of yearly dialogue for when you're living together. This dialogue system can be (and often is!) extendedly refined by setting dialogue specific to season, different heart levels, specific days (such as festivals or first day of the season), other weather conditions, and conversation topics (e.g., the community center being completed.).

Check the NPC Dialogue Template to get an idea, and the Dialogue modding guide for developpers on the main wiki for a thorough view.

Tip: They may even be crossover dialogues and conversation topics between mods! The modding community being close-knit, references may abound.

Events: Events may be a bit tricky to decipher, as their keys will often look like this:

"event-75160186.01": "line 1",
"event-75160186.02": "line 2",
"event-75160186.03": "line 3"

The translation keys here don't tell who's saying each line. You might want to check the code or, even better, play the event in the game to find out. To do this, run Stardew Valley with the mod and open a game. Then, enter the “Start Event” command in the console and hit "Enter". A message will tell you that "There was not output" – ignore that, the event will start as soon as you go back to your game app.

debug ebi [event id]

Following the example over here, you will enter debug ebi 75160186 to start the event.

Objects: Most objects have got two keys, name and description.

Mail: Each letter has got two keys, its "title" (its name in the collection tab) and its content.

Quests: Each quest has got at least three keys, its title, its content, and its objective(s).

Format and tricks

You may have to play around with commands, tokens and other “coding stuff” directly in the translatable text.

Here's an example with the most common commands and tokens:

   "translation-key-2": "Hi @! Here's some translatable text with a {{token}} value.#$b#Sweet, isn't it?$h"

The {{token}} value are going to be replaced with preset words when the mod runs, so don't change the text between {{ and }}. For example, if the text says "You have {{count}} gold", the player is going to see their current gold count in-game.

Here is a list of commands and tokens you'll often come across and what they mean:

@ The player's name.

#$b# Box break: This command separates two parts of the dialogue so the first is followed by the other in a new dialogue “box”.

#$e# Conversation break: This command separates two parts of the dialogue so you have to interact with the NPC again to continue the dialogue.

% Text box: Turns the dialogue box into a generic text box. Example: "%Abigail is lost in her music."

${male^female}$ ${male^female^non-binary}$ Gender switch: Change text depending on the player's gender. The non-binary value is only used if a mod overrides the player's gender, since the in-game UI only allows male or female.

"translation-key": "Hi, ${Mr.^Ms.}$ farmer!",
"translation-key": "I should find ${Mr.^Ms.^Mx.}$ @ to tell ${him^her^them}$ that ${his^her^their}$ chickens escaped..."

^ Gender switch - Deprecated. Most code should use the newer ${...} form above, which is supported in more places. The text before it is shown for male farmers, the text after it for female farmers. Example: Oh, good morning Mr. @!^Oh, good morning Ms. @!

$0 Portrait command: These set the portrait shown in the dialogue box for the current line of dialogue.

If there's no portrait command, the neutral portrait is used.

Portraits are numbered left-to-right and top-to-bottom, starting at $0. The first six portraits are standard, and can be identified by the number (like $2) or a unique alias (like $s). All potential spouses and many other characters have these six portraits, but it's not fully consistent; for example, Caroline only has four. Marriageable characters have usually got more portraits – their "love portrait" is the blushing one. You'll have to snoop around the mod files to find the image file depicting all the portraits if you want to

numbered	alias	description
`$0`		Use their neutral portrait.
`$1`	`$h`	Use their happy portrait.
`$2`	`$s`	Use their sad portrait.
`$3`	`$u`	Use their unique portrait. This is different for each NPC: grumpy (Abigail), holding football (Alex), angry (Caroline), sick (Governor), etc.
`$4`	`$l`	Use their love portrait.
`$5`	`$a`	Use their angry portrait.
`$<id>`		A custom portrait beyond the standard six.

Check the Dialogue modding guide for developpers on the main wiki for a thorough view.

Mail:

^ Line break.

¦ Gender switch character. The text before the ¦ command is shown to the male players and the text after it to female players. You can only use it once per letter, thus the entire letter content must be repeated.

Internationalization mod by bcmpinc

Internationalization is a mod for creating and updating translations for mods that use SMAPI's i18n API, to make translating mods more accessible for translators.

Translating

Your file is open, you understand what you're reading. Now it's time for the bulk of the work to start.

Translating assistance

Translating software (MT, or machine translation) and AI exist and it’s valid to use them! Their quality are variable but they might save you some time with translating the bunk of the text. It is however recommended to make a full rereading of the result, because the machine might struggle with NPC genders and singular/plural “you” as well as idioms, in-jokes and cultural references. Translating, however, isn't a case of “making the content available to your peers as soon as possible”. It's about respecting the modder's work by making your adaptation accurate and respecting the players by providing them a good translation too!

Tip: Use a thesaurus!

Making the translation better

Everybody has got their own standards and skills. This is not about judging yourself or each other, but about reaching your own standard. Here are some tips to refine your work (in particular when you use a translating software that might miss more subtle stuff):

Take care about your language characteristics (here's a few examples):

Formal/informal you,
Gendered words and determiners (especially for NPCs: AI may not recognise if the NPC is female/male/non-binary),
Suffixes,
And lots of other linguistic shenanigans!

Ask yourself questions about the content:

NPC: How does the NPC talk? formal or informal? How old are they? Which kind of humour do they prefer? Have they got speech patterns or tics (favourite word or expression, chattiness) that you can translate in your own language?

Oral and written form: Does the phrasing sound natural? Say the text aloud or picture yourself the characters talking to test the flow.

Objects: Has the object a specific or more usual name in your language?

Plants, animals and biological stuff: Switching the Wikipedia page of the species between different languages is a good way to get the name of a species, as is using the scientific name as reference. This is for people that enjoy (or cannot help) being thorough as heck!

Wordplay: Is the wordplay still fun in your language? If it isn’t, you may prefer to delete it, or better, to replace it with one that makes sense in your language!

Lore translation: Has the original name been kept as is in your language, or has it been adapted? Check the NPCs but also the locations and movies' names, and the local saying (how is “Void” translated in the game? what's the name of the money in your language?).

Testing

Json Validator

First, upload your .json file in SMAPI’s website Json validator here:

https://smapi.io/json

The website will tell if and where are the eventual issues in the code (missing commas and quotation marks are very common!).

In game

The SMAPI console will tell you if there’s a problem with a file (with a bunch of red text). Following are a few commands and mods you can use to test parts of your translation:

Dialogue: Enter the “Load Dialogue” command in the console.

debug loaddialogue [npcNameId] [dialogueKey]

Events: Enter the “Start Event” command in the console. See "More about translation keys" above.

debug ebi [event id]

Objects: Use the mods CJB Item Spawner or Lookup Anything to check the name and description of the item.

Tip: This is the moment to take screenshots of your translation in game! If you’re going to upload your files on their own page, they will make a nice presentation.

Uploading your translation

There are two ways to make your translation available to the community:

Send the .json file to the author of the mod so they can add it in their own files
Create a Nexus page on which players will find your files.

ASK THE MODDER: Some will require you to do one or the other. They may have already told you when you first got in contact with them. Because you did, didn’t you.

Including the translation in the original mod

Send your .json file as is or through Json Validator (after uploading your file, the website will give you a unique URL you can send to the modder for them to download).

Creating your translation’s own Nexus page

Go to “My Content” in your Nexus profile and choose “Add a file” in the upper right corner.

Now let’s fill out all the information! Don’t worry, the interface is user-friendly.

Tip: The mod won’t be made public until you click on the “I’m ready, publish my mod” button on the last step. You can save your draft and work on it as long as you want!

Preparing the file

For players to easily install your translation, you’ll want to put your file in the folder architecture of the original mod. For this, name your file with the prefix of your language and drop it in the i18n folder of the original mod. Then, delete every file you won’t need; keep only the folders leading to the i18n where you file is. That’s it!

Compress your mod in a zip format to upload it.

Tip for Mac users: You may get a “Some suspicious files” alert on your mod page (which disables download) if you archive it with the native Mac compressor (right-click/Archive [file name]). Use a free and OpenSource software like Keka to archive your file.

Tips to fill out the page manager

Mod details tabs:

Category: Same than the original mod
Mod name: Same name than the original mod + name/prefix of your language (+ “translation”)
Current version: Your translation’s, not the original mod! Start with 1.0 and increment each time you update the file
Detailed description: Quick presentation of the original mod and your translation. You may want to translate the whole description of the original mod.

Media:

Mod page header area/Your mod images (primary image): You have tacitly the right to reuse the banner and primary image of the original mod. You may add a country flag relevant of your language and/or the translation of the mod title in your language. You may use a completely different picture too!
Some screenshots showing the translated mod in game are a nice plus.

Tip: If others mods are visible on your screenshots (UI, recolours, sprites, clothes, etc.), add the references at the bottom of the description. That’s a nice thing to do!

Documentation:

Don’t forget to increment your version (1.1, 1.2, etc.) and describe what changed with each update in the Documentation tab (accessible through the “Log” tab on the public page of your mod).

Permissions:

The original text isn’t yours, but your translation is your original work. Here is a compromise to protect yours and the original modder’s work:

To the question “Does your file contain assets used from other authors (that you have permission to use) that can't be redistributed without permission?”, answer: No.
In the “Credits (Optional)” box, give the name of the original text's author.

One last tip? Okay!

DON’T FORGET TO TRACK THE ORIGINAL MOD, THE MODDER MAY NOT COME BACK TO YOU EVERY TIME THEY UPDATE THEIR MOD!

Navigation menu

Namespaces

Views

Navigation

Customizing this wiki

wiki.gg

Tools

Tutorial: Translating a mod using i18n

Contents

Choosing a mod

Translating

Software

Content of an i18n file

Translation keys

Format and tricks

Internationalization mod by bcmpinc

Translating

Translating assistance

Making the translation better

Testing

Json Validator

In game

Uploading your translation

Including the translation in the original mod

Creating your translation’s own Nexus page

Preparing the file

Tips to fill out the page manager

One last tip? Okay!

Navigation menu

Namespaces

Views

Search

Navigation

Customizing this wiki

wiki.gg

Tools

Tutorial: Translating a mod using i18n

Choosing a mod

Translating

Software

Content of an i18n file

Translation keys

Format and tricks

Internationalization mod by bcmpinc

Translating

Translating assistance

Making the translation better

Testing

Json Validator

In game

Uploading your translation

Including the translation in the original mod

Creating your translation’s own Nexus page

Preparing the file

Tips to fill out the page manager

One last tip? Okay!