Difference between revisions of "Modding:Custom languages"
Pathoschild (talk | contribs) (+ custom fonts) |
Pathoschild (talk | contribs) m (→Data format: remove unneeded 'now') |
||
Line 7: | Line 7: | ||
==Add a custom language== | ==Add a custom language== | ||
===Data format=== | ===Data format=== | ||
− | You can | + | You can add custom languages by editing the <tt>Data/AdditionalLanguages</tt> asset. Each entry consists of an object with these fields: |
{| class="wikitable" | {| class="wikitable" |
Revision as of 15:15, 29 October 2021
← Index
This page explains how to create custom languages in Stardew Valley 1.5.5+. This is an advanced guide for modders.
To translate text into an existing language, see Modding:Translations instead.
Add a custom language
Data format
You can add custom languages by editing the Data/AdditionalLanguages asset. Each entry consists of an object with these fields:
field | description |
---|---|
ID | A unique ID value. This is not shown in-game. |
LanguageCode | The language code for this localization. This should ideally be a ISO 639-1 code. You should avoid commas for compatibility with Content Patcher packs checking the {{Language}} token. |
ButtonTexture | The asset name for a 174x78 pixel texture containing the button of the language for language selection menu. The top half of the sprite is the default state, while the bottom half is the hover state. |
TimeFormat | A string which describes the in-game time format, with tokens replaced by in-game values. For example, [HOURS_12]:[MINUTES] [AM_PM] would show 12:00 PM at noon.
The valid tokens are:
|
ClockTimeFormat | A string which describes the in-game time format. Equivalent to TimeFormat, but used for the in-game clock. |
ClockDateFormat | A string which describes the in-game date format as shown in the in-game clock, with tokens replaced by in-game values. For example, [DAY_OF_WEEK]. [DAY_OF_MONTH] would show Mon. 1 .
The valid tokens are:
|
UseLatinFont | Whether the language uses the game's default fonts. If set to false, you must set the FontFile field. |
FontFile | (optional) The asset name for the font file to use (if UseLatinFont is false). See custom font below. |
FontPixelZoom | (optional) A factor by while to multiply the font size. |
FontApplyYOffset | (optional) Whether to shift the font up by four pixels (multiplied by the FontPixelZoom), to better align languages with larger characters like Chinese and Japanese. |
NumberComma | (optional) The string to use as the thousands separator (e.g. "," for 5,000,000 ). Defaults to a comma.
|
SmallFontLineSpacing | (optional) The line spacing value used by smallFont. Defaults to 26. |
UseGenderedCharacterTranslations | (optional) Whether the social tab and gift log will use gender-specific translations (like the vanilla Portuguese language). Defaults to false.
Specifically, this affects the Strings\StringsFromCSFiles:SocialPage.cs.11635 translation ("(Single)"). When enabled, it can contain male and female translations separated by |
Example
This Content Patcher pack would add Esperanto to the game. You should change Pathoschild.Esperanto to your mod's actual ID.
{
"Format": "2.0.0",
"Changes": [
// define language
{
"Action": "EditData",
"Target": "Data/AdditionalLanguages",
"Entries": {
"Pathoschild.Esperanto": { // for technical reasons, you need to specify the ID here *and* in the "ID" field
"ID": "Pathoschild.Esperanto",
"LanguageCode": "eo",
"ButtonTexture": "Mods/Pathoschild.Esperanto/Button",
"UseLatinFont": true,
"TimeFormat": "[HOURS_24_00]:[MINUTES]",
"ClockTimeFormat": "[HOURS_24_00]:[MINUTES]",
"ClockDateFormat": "[DAY_OF_WEEK] [DAY_OF_MONTH]"
}
}
},
// load button texture
{
"Action": "Load",
"Target": "Mods/Pathoschild.Esperanto/Button",
"FromFile": "assets/button.png"
}
]
}
Once the language is defined, you can add translations to the game by patching game assets like usual, and use the language code you specified above. For example:
{
"Action": "EditData",
"Target": "Strings/StringsFromCSFiles",
"Entries": {
"Game1.cs.3043": "Lundo",
"Game1.cs.3044": "Mardo",
...
},
"When": {
"Language": "eo"
}
}
Custom font
If you set UseLatinFont: false in the language data, you can provide your own Bitmap font with the FontFile field. This lets you map arbitrary Unicode characters to sprites in your font texture. You can unpack your game's Content folder and look at the Chinese, Japanese, Korean, and Russian fonts in the Fonts folder for some examples.
For example, here's the Content/Fonts/Japanese.fnt file (with most of the characters stripped out for brevity):
<?xml version="1.0"?>
<font>
<info face="SetoFont-SP" size="24" bold="0" italic="0" charset="" unicode="1" stretchH="100" smooth="1" aa="1" padding="0,0,0,0" spacing="1,1" outline="0"/>
<common lineHeight="24" base="21" scaleW="1024" scaleH="1024" pages="2" packed="0" alphaChnl="0" redChnl="4" greenChnl="4" blueChnl="4"/>
<pages>
<page id="0" file="Japanese_0" />
<page id="1" file="Japanese_1" />
</pages>
<chars count="2514">
...
<char id="37347" x="100" y="265" width="24" height="22" xoffset="0" yoffset="1" xadvance="24" page="0" chnl="15" />
...
</chars>
</font>
See the official format documentation to understand all the options, but at a high level:
field | description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
info | Describes the font itself: the name, TrueType size, padding and spacing, etc. | ||||||||||||||
common | Provides common info which applies to all of the characters, like the line height. | ||||||||||||||
pages | Lists the sprite textures that are part of the font. In the above example, the Japanese character sprites are split into two images: Japanese_0.png and Japanese_1.png. Each character in chars specifies which page it's on. | ||||||||||||||
chars | Maps each Unicode character you'll use in-game to the sprite font. The example above defines one character with these char fields:
|