{"id":13589310,"url":"https://github.com/BraceYourselfGames/UE-BYGLocalization","last_synced_at":"2025-04-08T09:32:32.334Z","repository":{"id":46250322,"uuid":"368721613","full_name":"BraceYourselfGames/UE-BYGLocalization","owner":"BraceYourselfGames","description":"Simple CSV localization system for Unreal Engine 4","archived":false,"fork":false,"pushed_at":"2022-03-26T16:31:07.000Z","size":90,"stargazers_count":82,"open_issues_count":2,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-14T22:02:34.482Z","etag":null,"topics":["engine","game-development","gamedev","internationalization","localization","plugin","ue4","ue4-plugin","unreal"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BraceYourselfGames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-19T02:27:00.000Z","updated_at":"2024-07-22T06:39:10.000Z","dependencies_parsed_at":"2022-07-26T13:17:12.332Z","dependency_job_id":null,"html_url":"https://github.com/BraceYourselfGames/UE-BYGLocalization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BraceYourselfGames%2FUE-BYGLocalization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BraceYourselfGames%2FUE-BYGLocalization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BraceYourselfGames%2FUE-BYGLocalization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BraceYourselfGames%2FUE-BYGLocalization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BraceYourselfGames","download_url":"https://codeload.github.com/BraceYourselfGames/UE-BYGLocalization/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223314070,"owners_count":17124994,"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":["engine","game-development","gamedev","internationalization","localization","plugin","ue4","ue4-plugin","unreal"],"created_at":"2024-08-01T16:00:27.769Z","updated_at":"2024-11-06T09:30:48.592Z","avatar_url":"https://github.com/BraceYourselfGames.png","language":"C++","funding_links":[],"categories":["Localization"],"sub_categories":[],"readme":"# BYG Localization\n\nWe wanted to support fan localization for [Industries of\nTitan](https://braceyourselfgames.com/industries-of-titan/) and found that\nUnreal's built-in localization system was not exactly what we wanted. So we\nmade our own!\n\nIt differs from Unreal's localization system in a few ways:\n\n* Only support a single CSV file as the authoritative source for strings.\n* Support creation and maintenance of fan translations.\n* Fallback to primary language if text is missing in a fan translation.\n* Clearer errors when keys are missing in a stringtable.\n* Support multiple localizations for the same language.\n\n\n\n## Feature Comparison\n\n| Feature | Unreal Localization | BYG Localization |\n| --- | --- | --- |\n| CSV stringtable support\t\t\t\t\t\t\t| :heavy_check_mark: \t| :heavy_check_mark:\t|\n| Add new keys in-editor\t\t\t\t\t\t\t| :heavy_check_mark:\t| :x:\t\t\t\t\t|\n| Reload text on CSV modification\t\t\t\t\t| :heavy_check_mark: \t| :heavy_check_mark:\t|\n| Support for fan translations\t\t\t\t\t\t| :x:\t\t\t\t\t| :heavy_check_mark:\t|\n| Show missing loc keys in-engine\t\t\t\t\t| :x:\t\t\t\t\t| :heavy_check_mark:\t|\n| Show fallback language text when keys are missing | :x:\t\t\t\t\t| :heavy_check_mark:\t|\n| Blueprint code support\t\t\t\t\t\t\t| :heavy_check_mark:\t| :heavy_check_mark:\t|\n| Multiple localizations for same language\t\t\t| :question:\t\t\t| :heavy_check_mark:\t|\n\n\n\n## Set-up\n\nFor this example, we will be using English as the **Primary Language**, but\nthe system works with using any language as the Primary language.\n\n### 1. Create CSV file\n\nWe are using English as the primary language for our game so we will create\n`loc_en.csv` inside `/Content/Localization/`, the default localization root\ndirectory for localization files. \n\n```\nKey,SourceString,Comment,English,Status\nHello_World,\"Hello world, how are you?\",General greeting.,,\nGoodbye_World,\"See you later!\",Shown when quitting the game.,,,\n```\n\n### 2. Configure the plugin\n\nOpen `Project Settings \u003e Plugins \u003e BYG Localization` and set the \nfollowing:\n\n- Primary Localization Directory should point to where you saved the\n  csv file.\n- Most other defaults should be OK.\n\nOpen `Window \u003e Developer Tools \u003e BYG Localization Stats`, and hit \nRefresh All. Your csv file should be listed there.\n\n![Stats window example](https://benui.ca/assets/unreal/byglocalization-statswindow.png)\n\n\n## Usage\n\n### Using Localized Text in Blueprints\n\nAfter adding the keys to the Stringtable CSV file, choose the entries for all\n`FText` properties by:\n\n1. Click on the drop-down arrow.\n2. Choose the Stringtable ID. BYG Localization defaults to \"Game\".\n3. Choose the key\n\n![Animation showing process for choosing a string entry](https://benui.ca/assets/unreal/stringtable.gif)\n\nIn Blueprint graphs, use `GetGameText` in `BYGLocalizationStatics`.\n\n### Getting Localized Text in C++ \n\n```cpp\nFText ButtonLabelText = UBYGLocalizationStatics::GetGameText( \"Hello_World\" );\n```\n\n### Changing the active locale\n\n```cpp\nFString PathToCSV;\nUBYGLocalizationStatics::SetActiveLocalization( PathToCSV );\n```\n\n### Stats Window\n\nThere is an stats window available in the editor for seeing which localization\nfiles have been detected by the system, how many entries they have, the status\nof those entries etc.\n\nAccess it through `Window \u003e Developer Tools \u003e BYG Localization Stats`.\n\n![Stats window example](https://benui.ca/assets/unreal/byglocalization-statswindow.png)\n\n### Customizing Settings\n\nAll of the project settings can be modified through `Project Settings \u003e Plugins \u003e BYG Localization` in the editor, or through\n`Config/DefaultBYGLocalization.ini`\n\nSettings include:\n* Localization file directories (default `/Localization/`)\n* Allowed filetypes (default `.csv` and `.txt`)\n* Filename prefix/suffix (default `loc_` prefix, no suffix)\n* Forcing quotation marks around all CSV values.\n\n\n\n## User Experience for Fan Localizers\n\n### Creating a new localization\n\n1. Create a file with the two-character [ISO 639-1 language\n   code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) and optional\n   region suffix. e.g. if the primary file is `loc_en.csv` and you want to\n   translate the game into French, create a file called `loc_fr.csv`\n2. Launch the game with the `-UpdateLoc` flag (create a desktop shortcut).\n3. Your `loc_fr.csv` file is now populated with all of the primary language\n   strings.\n\nAfter creating `loc_fr.csv` and running the game, your CSV file will look like\nthis:\n\n| Key | SourceString | Comment | Primary | Status |\n| --- | --- | --- | --- | --- |\n| `NewGameButtonLabel` | New Game | On main menu, starts new game | New Game | New Entry |\n| `ExitGameButtonLabel` | Quit | Exits the program | Quit | New Entry |\n\nAfter translation, your CSV file should look like this. You can remove the \"New Entry\" text from the Status column:\n\n| Key | SourceString | Comment | Primary | Status |\n| --- | --- | --- | --- | --- |\n| `NewGameButtonLabel` | Nouvelle partie | On main menu, starts new game. | New Game | _(blank)_ |\n| `ExitGameButtonLabel` | Quitter | Exits the program. | Quit | _(blank)_ |\n\n### Maintaining a localization\n\nAs the game is updated, strings will be added, removed or modified.\n* New strings will be shown with the status \"New Entry\", and will show up in the Primary Language until they are translated.\n* Modified will be shown with the status \"Modified\" and what the primary language text was before.\n* Removed strings will be shown with the status \"Deprecated\", or automatically removed (depending on the project settings).\n\n| Key | SourceString | Comment | Primary | Status |\n| --- | --- | --- | --- | --- |\n| `NewGameButtonLabel` | Nouvelle partie | On main menu, starts new game. | New Game | _(blank)_ |\n| `ExitGameButtonLabel` | Quitter | On main menu, starts new game. | Quit game | Modified: Was 'Quit' |\n| `LoadGameButtonLabel` | Load Game | Shows the load game screen. | Load Game | New Entry |\n\n\n\n## Installation\n\n### Source\n\n1. Download the zip or clone the repository to `ProjectName/Plugins/BYGLocalization`.\n2. Add `BYGLocalization` to `PrivateDependencyModuleNames` inside `ProjectName.Build.cs`.\n\n\n\n## Unreal Version Support\n\n* Compiles under Unreal Engine 4.22 up to 5.0EA\n* Tested mostly with 4.25 and 4.26\n\n\n\n## License\n\n* [3-clause BSD license](LICENSE)\n\n\n\n## Contact\n\n* Created and maintained by [@_benui](https://twitter.com/_benui) at [Brace Yourself Games](https://braceyourselfgames.com/)\n* Please report bugs through [GitHub](https://github.com/BraceYourselfGames/UE4-BYGLocalization/issues)\n\n\n\n## Future Work\n\n* Detecting runaway misquoted strings.\n* Allowing multiple stringtables, e.g. `loc_en_ui.csv`, `loc_en_dialog.csv`.\n* More tests!\n* Profiling and performance improvements.\n* Improve dir picker, see `DirectoryPathStructCustomization`\n* Add \"Export Changes\" function for exporting New and Modified entries for all\n  seelcted languages.\n\n\n\n## How it works\n\nThe plugin uses Project Settings to search for localization files in the\nspecified directories. It uses Unreal's String Table system to register both\nthe primary language (e.g. English) and the user's preferred language (e.g.\nFrench).\n\nFallback works in two ways:\n\n1) If text is set with `UBYGLocalizationStatics::GetText(const FString\u0026\nKeyName)` and the key is not found, the key is then looked up in the fallback\ntable.\n\n2) When running the game, all localization files are parsed and any missing\nkeys are added to non-primary localization files. This way `FText` properties\ninside Blueprints  will still find keys in the Stringtable for the user's\nselected locale.\n\n\n\n## FAQ\n\n### Q) I changed Stringtable Namespace and/or Stringtable ID and now my text is gone!\n\n**A)** Changing **Namespace** or **Stringtable ID** will break all of the\n`FText` strings in your Blueprints. You should only set these values once at\nthe start of the project, and not change them.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBraceYourselfGames%2FUE-BYGLocalization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBraceYourselfGames%2FUE-BYGLocalization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBraceYourselfGames%2FUE-BYGLocalization/lists"}