{"id":17039011,"url":"https://github.com/dcnick3/shin-translation-tools","last_synced_at":"2026-01-07T09:06:03.660Z","repository":{"id":209374466,"uuid":"723885915","full_name":"DCNick3/shin-translation-tools","owner":"DCNick3","description":"Translation-focused tools for the shin engine","archived":false,"fork":false,"pushed_at":"2025-03-31T11:25:36.000Z","size":476,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T12:28:42.297Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DCNick3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-27T00:57:18.000Z","updated_at":"2025-03-31T11:25:40.000Z","dependencies_parsed_at":"2024-02-15T17:28:26.670Z","dependency_job_id":"01d2e3e2-39e4-4727-af6e-cee9d19edd29","html_url":"https://github.com/DCNick3/shin-translation-tools","commit_stats":null,"previous_names":["dcnick3/shin-translation-tools"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Fshin-translation-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Fshin-translation-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Fshin-translation-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Fshin-translation-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DCNick3","download_url":"https://codeload.github.com/DCNick3/shin-translation-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406069,"owners_count":20933802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T08:58:26.551Z","updated_at":"2026-01-07T09:06:03.649Z","avatar_url":"https://github.com/DCNick3.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"A future home for translation-focused tools for the shin engine.\n\nI've already made a few tools for this engine:\n\n- [shin](https://github.com/DCNick3/shin) - a reimplementation of the umineko version of shin engine and `sdu` - a\n  companion tool for extracting game data\n- [ShinDataUtil](https://github.com/DCNick3/ShinDataUtil) - a comprehensive tool for extracting and repacking the game\n  data\n\nHowever, they target relatively modern versions of the engine (the former - switch's umineko, the latter - switch's\nhigurashi) and require a lot of work to add support for other versions.\n\nThe aim of this project is to provide tools that cover a wider range of versions.\n\nAs a starting point I'm targeting the \"AstralAir no Shiroki Towa -White Eternity-\" version of the engine.\n\n## Features\n\n- Extraction and compilation of ROM files compatible with, AFAIK, all* versions of the engine\n- Translation of the game script (SNR files). See [game support](#game-support) section to find out which games are\n  supported\n\n\\* except for PS2 versions, which embed rom files directly onto the disc\n\nIn the future I plan to implement more engine versions for the SNR translation tool, and maybe make a multi-version tool\nfor working with graphics (PIC and TXA).\n\n## Installation\n\n### Binary release\n\nDownload a release from the [releases page](https://github.com/DCNick3/shin-translation-tools/releases).\n\nFor Linux/macOS use the shell script installer. For Windows use either the powershell or msi installer.\n\n### From source\n\n```bash\ncargo install --path shin-tl\n```\n\n### Shell completion\n\nTo enable shell completion, generate the completion script and source it in your shell\n\nFor linux shells:\n\n```bash\nshin-tl generate-completion bash \u003e ~/.local/share/bash-completion/completions/shin-tl\nshin-tl generate-completion zsh \u003e ~/.local/share/zsh/site-functions/_shin-tl\nshin-tl generate-completion fish \u003e ~/.config/fish/completions/shin-tl.fish\n```\n\nFor powershell:\n\n```powershell\nshin-tl generate-completion powershell \u003e\u003e $PROFILE\n```\n\nThen re-start the shell or source the generated file\n\n## Game support\n\nAlthough ROM files are supported for all versions of the engine, the SNR translation tool requires support for each game\nseparately. See \"shin-tl snr support\" column in [this spreadsheet][games] to find out which games are supported.\n\nAf of writing this readme, vita versions of \"AstralAir no Shiroki Towa -White Eternity-\", \"ALIA's CARNIVAL!\nSacrament\" and \"Higurashi no Naku Koro ni Sui\" along with switch version of \"D.C.4 -Da Capo 4-\" are supported.\n\nNote that for games that have `commands style` set to `unescaped` (like ALIA's CARNIVAL! and Higurashi Sui) you will\nprobably want to convert the command styles as outlined\nin [this section](#dealing-with-ascii-characters-in-older-games).\n\nIf you want to translate some other games this engine uses, let me know, so I can prioritize support for that game.\n\n## Usage\n\n### Preparation\n\nFirst of all, you would need the game files. How you obtain it differs by the platform.\n\nOn Switch, you would need to first dump the game with [nxdumptool](https://github.com/DarkMatterCore/nxdumptool) and\nthen extract the romfs files with [hactoolnet](https://github.com/Thealexbarney/LibHac).\n\nWhen dealing with PS Vita files, make sure that you have the files decrypted.\n\nshin engine usually packages its files into one or two `.rom` files: `data.rom` and sometimes `patch.rom`. You would\nneed to obtain them first.\n\nAfter you have obtained the rom files, `shin-tl` can already handle them\n\n### Extracting the rom files\n\nTo extract the rom files, use a command like this:\n\n```bash\nshin-tl rom extract \u003cdata.rom\u003e \u003crom-dir\u003e\n```\n\nThis will create the `rom-dir` directory and extract the rom files into it.\n\nThe game stores its data in multitude of formats. The ones that are the most interesting for translation are:\n\n- `SNR` - the game script\n- `PIC` - pictures (mostly CGs)\n- `TXA` - texture archives (mostly UI elements)\n- `FNT` - fonts\n\nAs of now, shin-tl can only be used to translate the game script (`SNR` files).\n\n### Translating the SNR files\n\n1. Extract the strings\n\nTo extract strings from the snr file into a csv file, use a command like this:\n\n```bash\nshin-tl snr read \u003cengine-version\u003e \u003cmain.snr\u003e \u003cstrings.csv\u003e\n```\n\nThe format of the SNR files varies greatly with the engine version, and it does not contain any indicators as to which\nversion it is. Thus, you need to supply the engine version to the tool.\n\nSee \"shin-tl name\" column\nof [this spreadsheet][games]\ncorresponding to your game to find out what to put here.\n\nThe `strings.csv` file will contain the extracted strings. It can be edited with a spreadsheet editor like Excel or\nLibreOffice Calc.\n\nHere's how it will look like:\n\n```csv\nindex,offset,source,source_subindex,s,translated\n\u003c...\u003e\n53,0x00037e62,saveinfo,0,共通ルート,\n54,0x00037e71,saveinfo,0,プロローグ,\n55,0x00037f15,msgset,1,@rここは自由に駆け回れる庭だった。,\n56,0x00037f3a,msgset,2,@r好きに生きることを許された世界だった。,\n57,0x00037f62,msgset,3,@rそれ以上に求めるものはない。,\n58,0x00037f82,msgset,4,@rやわらかい雪の上に、想うだけ足跡をつけたなら、この心は簡単に満たされる。,\n\u003c...\u003e\n```\n\nThe `index` column is used to later inject the translated strings back into the SNR file, while `offset`, `source`\nand `source_subindex` provide information about where the string comes from.\n\nIf you are using a spreadsheet editor, take care to avoid conversion of the columns to numbers, as it will break the\ntool.\n\nIn case of Google Spreadsheets, make sure to uncheck the \"Convert text to numbers, dates and formulas\" option when\nimporting the csv:\n\n![](googledoc_import.png)\n\n2. Inject the translated strings back\n\nCreate a translation csv by putting your translated strings into the `translated` column. Don't change the strings in\n`s` column, those changes will be ignored.\n\nTo inject the translated strings back into the snr file, use a command like this:\n\n```bash\nshin-tl snr rewrite \u003cengine-version\u003e \u003cmain.snr\u003e \u003ctranslation.csv\u003e \u003cmain_translated.snr\u003e\n```\n\nThis will read the translation csv, replace the strings in the snr file and write the result to `main_translated.snr`.\n\nNOTE: you almost surely want to use text reflow options, see [this section](#soft-line-breaks) for details\n\n### Rebuild the rom file\n\nAfter touching all the files you wanted to translate, you would need to package them back into a `.rom` file.\n\nAll games I saw so far load the `patch.rom` file on top of `data.rom` (even if in original distribution there's\nno `patch.rom`). It also tends to be smaller, so you almost definitely want to put your translated files\ninto `patch.rom`.\n\nTo rebuild the rom file, use a command like this:\n\n```bash\nshin-tl rom create --rom-version \u003crom-or-game-version\u003e \u003crom-dir\u003e \u003cpatch.rom\u003e \n```\n\nThis will package all files and directories inside `rom-dir` into a `patch.rom` file.\n\nNote that the rom format varies from game to game, so you need to supply either the rom format (`rom1-v2-1`, `rom2-v1-0`\nor `rom2-v1-1`) or the engine version to the tool. You can see the correspondence\nin [this spreadsheet][games].\n\nAfter that, you can put the `patch.rom` file back into the game (however it is done on the platform you are working\nwith).\n\nOn Switch you would use LayeredFS mods to do that.\n\n## Message format\n\nSome strings can contain layout commands. These are strings for `MSGSET`, `LOGSET` and `SELECT` commands (they\ncorrespond to `msgset`, `logset` and `select_choice` values of `source` column in the CSV). They are interleaved with\nregular text and can change the way the text looks or perform some actions when reached.\n\nAll commands are represented by a single lowercase ASCII character. Some of them have a single argument that starts\nimmediately after the command character and is terminated by `.`. Argument can be a string (then it's treated literally)\nor a number (then it is parsed either as a decimal number or, if prefixed by `$`, as a hexadecimal).\n\nI am aware of two styles of the commands used in different versions of the engine:\n\n- Escaped. The more modern one, prefixes all commands with `@`. Example: `語り手@r@vhello.Hello.`\n- Unescaped. Can be found in order versions, all ASCII characters are implicitly treated as commands. `!` can be used to\n  escape those. Example: `語り手rvhello.!H!e!l!l!o.`\n\nOne version only ever uses a single style. You can see which is which in\nthe [game spreadsheet][games].\n\nFor documentation on which commands does what, you can\ncheck [this spreadsheet][layout-commands].\n\n### Dealing with ASCII characters in older games\n\nAs you might have noticed, making translation with unescaped command style to any language that uses ASCII characters\n`!c!a!n! !b!e! !c!u!b!m!e!r!s!o!m!e`. This is why `shin-tl` can seamlessly convert the scenario to the escaped format\nand back.\n\nTo use this, pass `--message-style modernize` parameter to __both__ the `snr read` and `snr rewrite`. The `read` will\nnow generate a CSV file in the escaped format (prefixing all commands with `@`), while `rewrite` will convert it back to\nequivalent unescaped form, using `!` to escape all literal ASCII characters.\n\nNote that if you don't pass `--message-style modernize` to `snr rewrire`, the tool will generate an SNR file with\nescaped commands that the engine won't be able to parse correctly. Hopefully, the enabled-by-default linting should help\nyou detect this.\n\n## Soft line breaks\n\nThe `shin` engine was not designed with western languages in mind, and so it's line breaking rules do not implement the\nusual word-wrapping logic that is applicable to western languages. It implements kinsoku shori which, basically, allows\nline breaks to be inserted everywhere except with some punctuation marks. What this means for western language\ntranslations though, is that without additional care taken, the game will simply insert linebreaks in the middle of\nwords, which is not nice.\n\nTo help you with this, `shin-translation-tools` implements text reflowing, allowing you to bake in some hard\nlinebreaks (`@r`), so that the game would not have to try and fail to line break itself. For this, a subset of game's\nlayouter is reimplemented which will position the characters and break them in positions which\n[UAX#14](https://www.unicode.org/reports/tr14/) (Unicode line breaking algorithm) will allow. This should support\nwide set of western languages and possibly some non-western ones too (although I have not tested this).\n\n### Text reflowing with `shin-translation-tools`\n\nTo reflow the text, in addition to the SNR file, you would need the FNT file used for messages in the game. Different\ngames use different font files (and names), so you can find which file you want in the\n[games spreadsheet][games] (`message font` column).\n\nWith font in hand, you have to pass it to `rewrite` command with `--font-file \u003cpath-to-fnt\u003e` and ask for reflow with\n`--reflow-mode greedy`. The full command line utilizing both message style modernization and reflowing could look like\nthis:\n\n`shin-tl snr rewrite --font-file gothic.fnt --reflow-mode greedy --message-style modernize higurashi-sui main.snr translation.csv main_translated.snr`\n\nNOTE: currently text reflowing is implemented only for `higurashi-sui`.\n\n[games]: https://docs.google.com/spreadsheets/d/1wGX9FOQq_iXcWMnY9qITCAV7hq1R7_gpWwjkT4_tKDI\n\n[layout-commands]: https://docs.google.com/spreadsheets/d/1HNYDUVUSKz9JTHieH7t8zYIt06KFTeOxExSCO6ZjatU/edit#gid=1796226786\n\n## Alternatives\n\nThere are alternatives to this project, which support other versions of the engine:\n\n- [ShinDataUtil](https://github.com/DCNick3/ShinDataUtil) (by me) has full support for (almost?) all formats used by\n  switch's Higurashi Hou and Konosuba\n- [sdu](https://github.com/DCNick3/shin#what-else-is-in-the-box) (also by me) has support for extraction (but not\n  creation) of most formats used by switch's Umineko\n- [enter_extractor](https://github.com/07th-mod/enter_extractor) (by 07th-mod) has support for extraction and patching\n  of most formats across several versions of the engine\n- [kaleido](https://gitlab.com/Neurochitin/kaleido/) (by Neurochitin) has support for scenario translation of vita's\n  umineko and vita and switch's Kaleido. There's also code to generate FNT files\n\n## License\n\nLicensed under Mozilla Public License 2.0. See [LICENSE](LICENSE) for more information.\n\n## Disclaimer\n\nThis is a fan project to enable unofficial translations of shin-based games. It is by no means affiliated with\nEntergram, Dramatic Create, Alchemist or any other rightsholder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcnick3%2Fshin-translation-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcnick3%2Fshin-translation-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcnick3%2Fshin-translation-tools/lists"}