{"id":20012319,"url":"https://github.com/archtechx/gloss","last_synced_at":"2025-05-04T20:31:29.858Z","repository":{"id":44737896,"uuid":"320965148","full_name":"archtechx/gloss","owner":"archtechx","description":"Brilliant localization for Laravel","archived":false,"fork":false,"pushed_at":"2023-02-16T10:38:21.000Z","size":34,"stargazers_count":37,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T14:12:28.797Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"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/archtechx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"stancl"}},"created_at":"2020-12-13T02:07:28.000Z","updated_at":"2024-08-28T16:15:42.000Z","dependencies_parsed_at":"2024-11-13T07:30:23.721Z","dependency_job_id":"c8014e20-4f3e-41e0-b86b-f5da8dacf119","html_url":"https://github.com/archtechx/gloss","commit_stats":{"total_commits":42,"total_committers":3,"mean_commits":14.0,"dds":0.04761904761904767,"last_synced_commit":"118981f8df57ddedc302c1ec689df46792e69f54"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archtechx%2Fgloss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archtechx%2Fgloss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archtechx%2Fgloss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/archtechx%2Fgloss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/archtechx","download_url":"https://codeload.github.com/archtechx/gloss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252395324,"owners_count":21741015,"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-11-13T07:29:44.330Z","updated_at":"2025-05-04T20:31:29.460Z","avatar_url":"https://github.com/archtechx.png","language":"PHP","funding_links":["https://github.com/sponsors/stancl"],"categories":[],"sub_categories":[],"readme":"# 🔍 Gloss ✨ — Brilliant localization for Laravel\n\nGloss is a Laravel package for advanced localization.\n\nLaravel's localization system is perfect for many languages, but it breaks down when you need a bit more control.\n\nFor example, some languages change words depending on the context they're used in. The words may get prefixed, suffixed, or even changed completely.\n\nAside from adding support for complex languages, Gloss also ships with quality of life improvements such as the ability to add formatting to a translation string.\n\n## Installation\n\nLaravel 6 or 8 is required, PHP 7.4 is required.\n\n```\ncomposer require leanadmin/gloss\n```\n\n## Configuration\n\nBy default, Gloss comes with the `gloss()` helper and `___()` helper.\n\nIf you wish, you may disable the `___()` helper by setting:\n```php\nuse Gloss;\n\nGloss::$underscoreHelper = false;\n```\n\nAnd if you wish to make all existing `__()` calls Gloss-aware:\n```php\nuse Gloss;\n\nGloss::$shouldReplaceTranslator = true;\n```\n\nA good place for these calls is the `boot()` method of your `LeanServiceProvider` or `AppServiceProvider`.\n\n## Usage\n\nGloss can be used just like the standard Laravel localization helpers:\n\n```php\n___('Create :Resource', ['resource' =\u003e 'product']);\n\n// 'resources.edit' =\u003e 'Show :Resource :title'\ngloss('resources.create', ['resource' =\u003e 'product', 'title' =\u003e 'MacBook Pro 2019']); // Show Product MacBook Pro 2019\n\n// 'notifications.updated' =\u003e ':Resource :title has been updated!'\nGloss::get('resources.edit', ['resource' =\u003e 'product', 'title' =\u003e 'iPhone 12']); // Product iPhone 12 has been updated!\n\n// 'foo.apple' =\u003e 'There is one apple|There are many apples'\nGloss::choice('foo.apple', ['count' =\u003e 2]); // There are many apples\n```\n\nHowever, unlike the standard localization, it lets you make changes to these strings on the fly:\n\n### Value overrides\n\nImagine that you're editing the `Order` resource in an admin panel. Your resource's singular label is `Objednávka`, which is Czech for `Order`.\n\nThe language string for the create button is\n```php\n// Original in English: 'create' =\u003e 'Create :Resource',\n'create' =\u003e 'Vytvořit :Resource',\n```\n\nIf we fill the value with the resource name, we get `Vytvořit Objednávka`. Unfortunately, that's wrong not once, but twice.\n\nFirstly, it should be Objednávk**u**, because the suffix changes with context. And secondly, it's grammatically incorrect to capitalize the word here.\n\n```diff\n- Vytvořit Objednávka\n+ Vytvořit objednávku\n```\n\nSo we want to specify a **complete override** of that language string whenever we're in the `Order` resource context.\n\nTo do this, simply call:\n```php\nGloss::value('resource.create', 'Vytvořit objednávku');\n```\n\n(From an appropriate place, where the application is working with the Order resource.)\n\nIf you're using Lean, this is taken care of for you. You can simply define entire language strings in the `$lang` property of your resource, and they'll be used in all templates which use the resource.\n\nAlso note that the example above mentions resources, but that's just how Lean is implemented. Gloss will work with any setup.\n\nYou can also set multiple value overrides in a single call:\n\n```php\nGloss::values([\n    'resource.create' =\u003e 'Vytvořit objednávku',\n    'resource.edit' =\u003e 'Upravit objednávku',\n]);\n```\n\nYou may also use the `gloss()` helper for this. Simply pass the array as the first argument.\n\n### Scoping overrides\n\nSometimes you may want to scope your overrides. For example, rather than overriding all `resource.create` with `Vytvořit objednávku`, you may want to only do that if the `resource` parameter is `order`.\n\nTo do this, pass a third argument:\n\n```php\nGloss::value('resource.create', 'Vytvořit objednávku', ['resource' =\u003e 'order');\n```\n\nThe condition can also be passed to `values()`:\n```php\nGloss::values([\n    'resource.create' =\u003e 'Vytvořit objednávku',\n    'resource.edit' =\u003e 'Upravit objednávku',\n], ['resource' =\u003e 'order']);\n```\n\nOr to the `gloss()` helper when setting overrides:\n\n```php\ngloss([\n    'resource.create' =\u003e 'Vytvořit objednávku',\n    'resource.edit' =\u003e 'Upravit objednávku',\n], ['resource' =\u003e 'order']);\n```\n\n### Key overrides\n\nTo build up on the example above, let's say our admin panel uses multiple languages. So replacing the language string with a translation that's part of the code isn't feasible.\n\nFor this reason, Gloss also lets you alias keys to another keys:\n\n```php\n// 'orders.create' =\u003e 'Vytvořit objednávku',\n// 'resources.create' =\u003e 'Vytvořit :resource',\n\nGloss::key('resource.create', 'orders.create');\n```\n\nThis is equivalent to fetching the value using a translation helper.\n```php\nGloss::value('resource.create', gloss('orders.create'));\nGloss::key('resource.create', 'orders.create');\n```\n\nAs with `value()`, you can pass conditions:\n```php\nGloss::key('resource.create', 'orders.create', ['resource' =\u003e 'order');\n```\n\n### Extending values\n\nYou may also build upon fully resolved language strings.\n\nFor example, consider the following example:\n```html\nShowing \u003cstrong\u003e10\u003c/strong\u003e to \u003cstrong\u003e20\u003c/strong\u003e of \u003cstrong\u003e50\u003c/strong\u003e results.\n```\n\nTo localize this, we'd either have to localize each word separately (which is what Laravel does, and it breaks down similarly to the \"Order\" word example), or we'd have to add the markup to the translation strings (which sucks for security, translator life quality), or we'd have to ditch the formatting completely.\n\nAll of those are unnecessary trade-offs.\n\nGloss lets you add formatting after the string is fully built:\n\n```php\n// 'pagination' =\u003e 'Showing :start to :end of :total results',\n\nGloss::extend('foo.pagination', fn ($value, $replace) =\u003e $replace($value, [\n    ':start' =\u003e '\u003cspan class=\"font-medium\"\u003e:start\u003c/span\u003e',\n    ':end' =\u003e '\u003cspan class=\"font-medium\"\u003e:end\u003c/span\u003e',\n    ':total' =\u003e '\u003cspan class=\"font-medium\"\u003e:total\u003c/span\u003e',\n]));\n\nGloss::get('foo.pagination', ['start' =\u003e 10, 'end' =\u003e 20, 'total' =\u003e 50])\n// Showing \u003cspan class=\"font-medium\"\u003e10\u003c/span\u003e to \u003cspan class=\"font-medium\"\u003e20\u003c/span\u003e of \u003cspan class=\"font-medium\"\u003e50\u003c/span\u003e results\n```\n\nOf course, `extend()` works perfectly with localized strings:\n```php\n// 'pagination' =\u003e 'Zobrazeno :start až :end z :total výsledků',\n\n// Zobrazeno \u003cspan class=\"font-medium\"\u003e10\u003c/span\u003e až \u003cspan class=\"font-medium\"\u003e20\u003c/span\u003e z \u003cspan class=\"font-medium\"\u003e50\u003c/span\u003e výsledků\n```\n\nIt even works with pluralized/choice-based strings:\n\n```php\n// 'apples' =\u003e '{0} There are no apples|[1,*]There are :count apples'\n\nGloss::extend('foo.apples', fn ($apples, $replace) =\u003e $replace($apples, [\n    ':count' =\u003e '\u003cspan class=\"font-medium\"\u003e:count\u003c/span\u003e',\n]));\n\ngloss()-\u003echoice('foo.apples', 0); // There are no apples\ngloss()-\u003echoice('foo.apples', 5); // There are \u003cspan class=\"font-medium\"\u003e5\u003c/span\u003e apples\n```\n\nThe second argument is a callable that can return any string, but in most cases this will simply be the resolved string with a few segments replaced.\n\nFor that reason, Gloss automatically passes `$replace` to the callable, which lets you replace parts of the string using beautiful, arrow function-compatible syntax.\n\n```php\n// So elegant!\n\nfn ($string, $replace) =\u003e $replace($string, [\n   'elegant' =\u003e 'eloquent',\n]);\n\n// So eloquent!\n```\n\n### Callable translation strings\n\nGloss also adds support for callable translation strings.\n\nThose can be useful when you have some code for dealing with things like inflection.\n\nFor example, consider these three language strings:\n```php\n'index' =\u003e ':resources',\n'create' =\u003e 'Create :resource',\n'edit' =\u003e 'Edit :resource :title',\n'delete' =\u003e 'Delete :resource :title',\n```\n\nIn many languages that have declension (inflection of nouns, read more about the complexities of localization on [in our documentation](https://lean-admin.dev/docs/localization)), the form of `:Resource` will be the same for `create`, `edit`, and `delete`.\n\nIt would be painful to translate each string manually for no reason. A better solution is to use intelligent inflection logic **as the default, while still keeping the option to manually change specific strings if needed**.\n\n```php\n'index' =\u003e fn ($resource) =\u003e nominative($resource, 'plural'),\n'create' =\u003e fn ($resource) =\u003e 'Vytvořit ' . oblique($resource, 'singular'),\n'edit' =\u003e fn ($resource, $title) =\u003e 'Upravit ' . oblique($resource, 'singular') . $title,\n'delete' =\u003e fn ($resource, $title) =\u003e 'Smazat ' . oblique($resource, 'singular') . $title,\n```\n\nYou could have logic like this (with your own helpers) for the default values, and only use the overrides when some words are have irregular grammar rules and need custom values.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchtechx%2Fgloss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchtechx%2Fgloss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchtechx%2Fgloss/lists"}