{"id":13693012,"url":"https://github.com/xleon/I18N-Portable","last_synced_at":"2025-05-02T21:31:04.789Z","repository":{"id":5351696,"uuid":"52918118","full_name":"xleon/I18N-Portable","owner":"xleon","description":"Simple and cross platform internationalization/translations for Xamarin and .NET","archived":true,"fork":false,"pushed_at":"2023-11-12T23:49:43.000Z","size":781,"stargazers_count":106,"open_issues_count":16,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-30T01:34:38.794Z","etag":null,"topics":["dotnet","i18n","internationalization","localization","translations","xamarin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xleon.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-03-01T23:30:03.000Z","updated_at":"2024-05-09T14:07:08.000Z","dependencies_parsed_at":"2024-01-08T01:44:32.603Z","dependency_job_id":"e9a7a5a0-fc50-4aef-ba14-f7f7a0c044a0","html_url":"https://github.com/xleon/I18N-Portable","commit_stats":{"total_commits":159,"total_committers":4,"mean_commits":39.75,"dds":0.03144654088050314,"last_synced_commit":"b2692e1f0a789bb66af13e9e6b008428730a5a13"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xleon%2FI18N-Portable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xleon%2FI18N-Portable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xleon%2FI18N-Portable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xleon%2FI18N-Portable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xleon","download_url":"https://codeload.github.com/xleon/I18N-Portable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224337252,"owners_count":17294689,"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":["dotnet","i18n","internationalization","localization","translations","xamarin"],"created_at":"2024-08-02T17:01:04.466Z","updated_at":"2024-11-12T19:30:18.695Z","avatar_url":"https://github.com/xleon.png","language":"C#","funding_links":[],"categories":["Internationalization"],"sub_categories":[],"readme":"\u003e This project is now archived as there are no plans to update it.\n\u003e Please consider it before using it.\n\n\n# I18N-Portable\nSimple and cross platform internationalization/translations for Xamarin and .NET\n\n[![NuGet](https://img.shields.io/nuget/v/i18nportable?style=for-the-badge)](https://www.nuget.org/packages/I18NPortable/) \n[![NuGet](https://img.shields.io/nuget/dt/i18nportable?style=for-the-badge)](https://www.nuget.org/packages/I18NPortable/) \n[![AppVeyor](https://img.shields.io/appveyor/ci/xleon/i18n-portable?style=for-the-badge)](https://ci.appveyor.com/project/xleon/i18n-portable) \n[![Codecov](https://img.shields.io/codecov/c/github/xleon/I18N-Portable?style=for-the-badge)](https://codecov.io/gh/xleon/I18N-Portable)\n\n- Cross platform\n- Simple to use: `\"key\".Translate()`.\n- Simple and fluent initialization setup.\n- Readable locale files (.txt with key/value pairs).\n- Support for custom file formats (json, xml, etc)\n- Light weight\n- No dependencies.\n- Well tested\n\n![https://cloud.githubusercontent.com/assets/145087/24824462/c5a0ecce-1c0b-11e7-84d3-4f0fa815c9da.png](https://cloud.githubusercontent.com/assets/145087/24824462/c5a0ecce-1c0b-11e7-84d3-4f0fa815c9da.png)\n\n\n### Install\n\nInstall it on your PCL and platform projects.\nFrom nuget package manager console: \n\n`PM\u003e Install-Package I18NPortable`\n\n### Setup locales\n\n- In your PCL/Core project, create a directory called \"Locales\".\n- Create a `{languageCode}.txt` file for each language you want to support. `languageCode` can be a two letter ISO code or a culture name like \"en-US\". See [full list here](https://msdn.microsoft.com/en-us/library/ee825488%28v=cs.20%29.aspx).\n- Set \"Build Action\" to \"Embedded Resource\" on the properties of each file         \n\n**Locale content sample**\n\n    # key = value (the key will be the same across locales)\n    one = uno\n    two = dos\n    three = tres \n    four = cuatro\n    five = cinco\n      \n    # Enums are supported\n    Animals.Dog = Perro\n    Animals.Cat = Gato\n    Animals.Rat = Rata\n    Animals.Tiger = Tigre\n    Animals.Monkey = Mono\n     \n    # Support for string.Format()\n    stars.count = Tienes {0} estrellas\n     \n    TextWithLineBreakCharacters = Line One\\nLine Two\\r\\nLine Three\n     \n    Multiline = Line One\n        Line Two\n        Line Three\n\n[Other file formats (including custom) supported](https://github.com/xleon/I18N-Portable#custom-formats)\n\n### Fluent initialization\n\n```csharp\nI18N.Current\n    .SetNotFoundSymbol(\"$\") // Optional: when a key is not found, it will appear as $key$ (defaults to \"$\")\n    .SetFallbackLocale(\"en\") // Optional but recommended: locale to load in case the system locale is not supported\n    .SetThrowWhenKeyNotFound(true) // Optional: Throw an exception when keys are not found (recommended only for debugging)\n    .SetLogger(text =\u003e Debug.WriteLine(text)) // action to output traces\n    .SetResourcesFolder(\"OtherLocales\") // Optional: The directory containing the resource files (defaults to \"Locales\")\n    .Init(GetType().GetTypeInfo().Assembly); // assembly where locales live\n```\n\n### Usage\n\n```csharp\nstring one = \"one\".Translate();\nstring notification = \"Mailbox.Notification\".Translate(\"Diego\", 3); // same as string.Format(params). Output: Hello Diego, you've got 3 emails\nstring missingKey = \"missing\".Translate(); // if the key is not found the output will be $key$. Output: $missing$\nstring giveMeNull = \"missing\".TranslateOrNull(); // Output: null\n\nstring dog = Animals.Dog.Translate(); // translate enum value (Animals is an Enum backed up in the locale file with \"Animals.Dog = Perro\")\n\nList\u003cstring\u003e animals = I18N.Current.TranslateEnumToList\u003cAnimals\u003e(); \n\nList\u003cTuple\u003cAnimals, string\u003e\u003e animals = I18N.Current.TranslateEnumToTupleList\u003cAnimals\u003e();\nstring dog = animals[0].Item2; // Perro\n\nDictionary\u003cAnimals, string\u003e animals = I18N.Current.TranslateEnumToDictionary\u003cAnimals\u003e();\nstring dog = animals[Animals.Dog]; // Perro\n\n// List of supported languages (present in the \"Locales\" folder) in case you need to show a picker list\nList\u003cPortableLanguage\u003e languages = I18N.Current.Languages; // Each `PortableLanguage` has 2 strings: Locale and DisplayName\n\n// change language on runtime\nI18N.Current.Language = language; // instance of PortableLanguage\n\n// change language on runtime (option 2)\nI18N.Current.Locale = \"fr\";\n```\t\n\n### Data binding\n\n`I18N` implements `INotifyPropertyChanged` and it has an indexer to translate keys. For instance, you could translate a key like:\n\n    string three = I18N.Current[\"three\"]; \n\nWith that said, the easiest way to bind your views to `I18N` translations is to use the built-in indexer \nby creating a proxy object in your ViewModel:\n\n```csharp\npublic abstract class BaseViewModel\n{\n    public II18N Strings =\u003e I18N.Current;\n}\n```\n\n**Xaml sample**\n```xaml\n\u003cButton Content=\"{Binding Strings[key]}\" /\u003e\n```\n**Xamarin.Forms sample**\n```xaml\n\u003cButton Text=\"{Binding Strings[key]}\" /\u003e`\n```    \n**Android/MvvmCross sample**\n```xml\n\u003cTextView local:MvxBind=\"Text Strings[key]\" /\u003e\n```                \n**iOS/MvvmCross sample**\n\n```csharp\nvar set = this.CreateBindingSet\u003cYourView, YourViewModel\u003e();\nset.Bind(anyUIText).To(\"Strings[key]\");\n```\n\n\n\n### Supported formats\n\nThe library ships with a single format reader/parser that is [TextKvpReader](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable/Readers/TextKvpReader.cs). Any other reader will be isolated in a different nuget/plugin to keep the library as simple as possible.\n\n| Reader        | Format        | Source  |\n| ------------- |:-------------:| :-----:|\n| [TextKvpReader](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable/Readers/TextKvpReader.cs)    | [See sample](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable.UnitTests/Locales/es.txt) | I18NPortable |\n| [JsonKvpReader](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable.JsonReader/JsonKvpReader.cs)    | [See sample](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable.UnitTests/JsonKvpLocales/es.json) | I18NPortable.JsonReader [![I18NPortable.JsonReader](https://img.shields.io/nuget/v/I18NPortable.JsonReader.svg?maxAge=50000)](https://www.nuget.org/packages/I18NPortable.JsonReader/) |\n| [JsonListReader](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable.JsonReader/JsonListReader.cs)   | [See sample](https://github.com/xleon/I18N-Portable/blob/master/I18NPortable.UnitTests/JsonListLocales/es.json) | I18NPortable.JsonReader [![I18NPortable.JsonReader](https://img.shields.io/nuget/v/I18NPortable.JsonReader.svg?maxAge=50000)](https://www.nuget.org/packages/I18NPortable.JsonReader/) |\n\nTo use any non-default format, it needs to be added on initialization:\n\n```csharp\nI18N.Current\n    .AddLocaleReader(new JsonKvpReader(), \".json\") // ILocaleReader, file extension\n    // add more readers here if you need to\n    .Init(GetType().Assembly);\n```\n\n### Creating a custom reader for another file format:\n\nIt's very easy to create custom readers/parsers for any file format you wish.\nFor instance, lets take a loot at the above mentioned `JsonKvpReader`:\n\nGiven this __en.json__ file\n```json\n{\n  \"one\": \"uno\",\n  \"two\": \"dos\",\n  \"three\": \"tres\"\n}\n```\n\nCreating a custom reader is as simple as implementing `ILocaleReader`:\n\n```csharp\npublic interface ILocaleReader\n{\n    Dictionary\u003cstring, string\u003e Read(Stream stream);\n}\n```\n\n```csharp\npublic class JsonKvpReader : ILocaleReader\n{\n    public Dictionary\u003cstring, string\u003e Read(Stream stream)\n    {\n        using (var streamReader = new StreamReader(stream))\n        {\n            var json = streamReader.ReadToEnd();\n\n            return JsonConvert\n                .DeserializeObject\u003cDictionary\u003cstring, string\u003e\u003e(json)\n                .ToDictionary(x =\u003e x.Key.Trim(), x =\u003e x.Value.Trim().UnescapeLineBreaks());\n        }\n    }\n}\n```\n\n### Contributing new readers\n\nIf you implemented a new reader for another file format and you want to contribute, feel free to make a pull request. Any new reader will live in their own project in the solution and will produce a different nuget as a plugin to I18NPortable.\n\n    \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxleon%2FI18N-Portable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxleon%2FI18N-Portable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxleon%2FI18N-Portable/lists"}