{"id":30663717,"url":"https://github.com/simoncahill/libborr","last_synced_at":"2026-04-09T23:05:10.502Z","repository":{"id":65660035,"uuid":"596763805","full_name":"SimonCahill/libborr","owner":"SimonCahill","description":"Libborr is a cross-platform language file parser; useful for providing an easy way of translating your C++ application to other languages!","archived":false,"fork":false,"pushed_at":"2023-10-05T08:25:53.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-13T03:52:13.902Z","etag":null,"topics":["cpp17","cross-platform","language","library","linux","macos","translation","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SimonCahill.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}},"created_at":"2023-02-02T21:55:56.000Z","updated_at":"2023-03-12T16:49:20.000Z","dependencies_parsed_at":"2023-09-22T14:15:30.132Z","dependency_job_id":"c00a91eb-98f1-417a-9865-ceda6f1b342a","html_url":"https://github.com/SimonCahill/libborr","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/SimonCahill/libborr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCahill%2Flibborr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCahill%2Flibborr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCahill%2Flibborr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCahill%2Flibborr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimonCahill","download_url":"https://codeload.github.com/SimonCahill/libborr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonCahill%2Flibborr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278941260,"owners_count":26072659,"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","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cpp17","cross-platform","language","library","linux","macos","translation","windows"],"created_at":"2025-08-31T17:54:02.239Z","updated_at":"2025-10-08T12:16:12.673Z","avatar_url":"https://github.com/SimonCahill.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libborr\n\nlibborr - named after the Norse god of language and speech - is a cross-platform translation provider written in C++.\nlibborr uses a custom, ini-based file format which contains meta information about the translations and language within.\n\n# STATUS\nThis library is currently in its beta phase and may be subject to breaking changes!\n\n# Supported Features\n\nlibborr supports splitting translations into sections, allowing for the same translation name to be used across different portions of your application.\nIt also allows for meta-information to be stored for each language; some of which is required for the parser:\n\n| Required field    | Value                                 | Example                               |\n|-------------------|---------------------------------------|---------------------------------------|\n| lang_id           | The ID of the language as lang_REGION | lang_id = \"en_GB\"                     |\n| lang_ver          | The version of the language file      | lang_ver = \"1.0.0\"                    |\n| lang_desc         | A brief description of the language   | lang_desc = \"The English translation\" | \n\nOther, custom fields, may be added at your will and requirement.\nThese will be stored under the section `\"\"` and can be retrieved by using `lang.getString(\"\", \"your_custom_field\");`.\n\nWhat you do with these values is entirely up to your application.\nFailing in providing the required fields will result in a failed parse.\n\n## Sections\n\nA section in a borr file splits translations from one another. This is based in the ini-format.\nA section may contain an arbitrary number of fields, containing translations.\n\nA section must consist of text surrounded by square brackets:; `[section]`.\nThe text within the brackets must meet the following criteria:\n - begin with a lower- or uppercase letter or underscore\n - may be an arbitrary length\n - may contain any of the following characters: `A-z 0-9 _`\n\nSections not meeting this criteria will not be recognised and ignored.\nThis behaviour is by design and **not a bug!**\n\n```borrfile\n[my_section]\nmy_field = \"My translation\"\n\n[another_section]\nmy_field = \"A different translation\"\n```\n\n## Fields\nlibborr supports two separate types of fields; each field is however a `string`.\n\n### single-line fields\nSingle-line fields are likely the most common type of field you'll use.\nOne field consists of a single line of text, but supports a myriad of special characters.\n\n```borrfile\nmy_field = \"a single line\"\n```\n\n### multi-line fields\nlibborr also supports multi-line fields for use in your application.\nA multiline field is similar in structure to single-line fields, suffixed with a `[]` at the end.\n\nAlthough the fields are separate in the file, they will be concatenated within the parser.\nMultiline fields may also be separated by other fields.\n\n```borrfile\nmy_multiline_field[] = \"Line 1\"\nmy_multiline_field[] = \"Line 2\"\nmy_multiline_field[] = \"Line 3\"\nsingleline_field     = \"Some other translation\"\nmy_multiline_field[] = \"Line 4\"\n```\n\n## Variables\nlibborr supports the use of variables - which are text replacements which happen during runtime.\n\nEach application using libborr can define custom variable expanders which can be set across all languages loaded.\n\n\n```borrfile\n[translations_w_variables]\nmy_multiline_field[] = \"${myCustomVar} is a custom-expanded variable.\"\nmy_multiline_field[] = \"libborr also provides default expansions, such as ${date}\"\nmy_multiline_field[] = \"${time}.\"\nreference_to_other_field = \"Libborr can reference other translations and field. ${other_translations:some_field} like this!\"\n\n[other_translations]\nsome_field = \"Something\"\n```\n\n### Setting a custom expander\nA custom expander is a C++ function object which returns an `std::string` object and takes a `const string\u0026` as a function parameter.\n\nCustom expanders are searched before searching for default expanders and other translations in (potentially) other sections.\n\n```cpp\n// setting a custom expander\nborr::language::addVarExpansionCallback(\n     \"myCustomVar\", [](const string\u0026 var) {\n          // var is the trimmed name of the variable\n          // in the borrfile, the variable is written ${myCustomVar},\n          // var thus contains \"myCustomVar\"\n          return \"Some computed or otherwise dynamic expression/text\";\n     }\n);\n\n// removing a custom expander\nborr::language::removeVarExpansionCallback(\"myCustomVar\");\n```\n\nDefault variable expanders can also be overwritten by using the above method.\nIf the default expansion behaviour for `${date}` doesn't suit your needs, then it can be overridden by your application.\n\n## File Structure\nAs allured to at the beginning, borrfiles require a specific structure.\n\nThis section describes the file structure and provides examples.\n\n| Structure  | Description                                   | Example                                   |\n|------------|-----------------------------------------------|-------------------------------------------|\n| lang_desc  | The language description description field.   | lang_desc = \"English (United Kingdom)\"    |\n| lang_id    | The language ID with region and country.      | lang_id = \"en_GB\"                         |\n| lang_ver   | The language file's current version.          | lang_ver = \"v1.0.0\" (v is optional!)      |\n| #          | A comment. Comments can start anywhere.       | # this is a comment in my langfile        |\n| [section]  | A new language section; for pages or menus.   | [home_page] # translations for home page  |\n| field      | A field is a string container                 | page_title = \"My Home Page!\"              |\n| field[]    | A multi-line field.                           | about[] = \"This is an example of multi-\"  |\n| field[]    | A multi-line field.                           | about[] = \"line translation fields.\"      |\n| ${}        | A variable; used for text replacement.        | awesome = \"${page_title} Is Awesome!\"     |\n| ${s:f}     | A special variable; used for text replacement.| field = \"© ${home_page:page_title}        |\n\n### Example\nAn example file can be found in [here](https://github.com/SimonCahill/libborr/blob/master/reference/resources/en_GB.borr).\n\n## Library Usage\n\nA reference implentation can be found [here](https://github.com/SimonCahill/libborr/blob/master/reference/src/Main.cpp).\n\nBut here are some examples for a quick look.\n\n### Parsing a file\n\n```cpp\n#include \u003cborr/language.hpp\u003e\n\n#include \u003cifstream\u003e\n#include \u003cfilesystem\u003e\n#include \u003csstream\u003e\n\nvoid loadFromFile() {\n     borr::language enLang;\n\n     namespace fs = std::filesystem;\n     try {\n          borr::language::fromFile(fs::directory_entry(\"/path/to/en_GB.borr\", enLang));\n     } catch (const std::exception\u0026 ex) {\n          // handle exception here\n     }\n}\n\nvoid loadFromString() {\n     borr::language::deLang;\n\n     namespace fs = std::filesystem;\n\n     try {\n          stringstream sStream;\n          ifstream ifStream(\"/path/to/de_DE.borr\", deLang);\n\n          sStream \u003c\u003c ifStream.rdbuf();\n\n          borr::language::fromString(sStream.str(), deLang);\n     } catch (const std::exception\u0026 ex) {\n          // handle exception here\n     }\n}\n```\n\n### Reading translations\nReading translations is as simple as parsing a borrfile.\nYou have several options, such as disabling variable expansion.\n\nlibborr will not fail if your string was not found, because libborr returns an `std::optional\u003cstring\u003e` for the value.\n\n```cpp\nvoid foo(const language\u0026 lang) {\n     const auto translationWithExpandedVars = lang.getString(\"section\", \"field\");\n     const auto translationWithoutExpandedVars = lang.getString(\"section\", \"field\", false);\n\n     // do something\n     bar(translationWithExpandedVars.value_or(\"some replacement value\"));\n\n     // do something else\n     if (!translationWithoutExpandedVars.has_value()) {\n          // handle error or something\n     }\n}\n```\n\n### Getting entire sections\nIf, for whatever reason, you want to get the entire section, this is also possible.\nAs with individual translations, libborr will \"fail\" silently, using `std::optional\u003csect_t\u003e`.\n\n```cpp\nvoid foobar(const language\u0026 lang) {\n     const auto section = lang.getSection(\"my_section\");\n\n     for (const auto\u0026 field : section) {\n          field-\u003efirst; // is the field name\n          field-\u003esecond; // is the actual contents\n     }\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimoncahill%2Flibborr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimoncahill%2Flibborr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimoncahill%2Flibborr/lists"}