From 8233f84c5bf0d40c99860350976270502488f089 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samuel=20=C5=A0tancl?= <samuel.stancl@gmail.com>
Date: Mon, 14 Dec 2020 13:19:54 +0100
Subject: [PATCH] Document scoping

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index add04a7..5405dc3 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ Gloss::choice('foo.apple', ['count' => 2]); // There are many apples
 
 However, unlike the standard localization, it lets you make changes to these strings on the fly:
 
-### Value aliases
+### Value overrides
 
 Imagine that you're editing the `Order` resource in an admin panel. Your resource's singular label is `Objednávka`, which is Czech for `Order`.
 
@@ -87,7 +87,45 @@ If you're using Lean, this is taken care of for you. You can simply define entir
 
 Also note that the example above mentions resources, but that's just how Lean is implemented. Gloss will work with any setup.
 
-### Key aliases
+You can also set multiple value overrides in a single call:
+
+```php
+Gloss::values([
+    'resource.create' => 'Vytvořit objednávku',
+    'resource.edit' => 'Upravit objednávku',
+]);
+```
+
+You may also use the `gloss()` helper for this. Simply pass the array as the first argument.
+
+### Scoping overrides
+
+Sometimes 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`.
+
+To do this, pass a third argument:
+
+```php
+Gloss::value('resource.create', 'Vytvořit objednávku', ['resource' => 'order');
+```
+
+The condition can also be passed to `values()`:
+```php
+Gloss::values([
+    'resource.create' => 'Vytvořit objednávku',
+    'resource.edit' => 'Upravit objednávku',
+], ['resource' => 'order']);
+```
+
+Or to the `gloss()` helper when setting overrides:
+
+```php
+gloss([
+    'resource.create' => 'Vytvořit objednávku',
+    'resource.edit' => 'Upravit objednávku',
+], ['resource' => 'order']);
+```
+
+### Key overrides
 
 To 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.
 
@@ -106,6 +144,11 @@ Gloss::value('resource.create', gloss('orders.create'));
 Gloss::key('resource.create', 'orders.create');
 ```
 
+As with `value()`, you can pass conditions:
+```php
+Gloss::key('resource.create', 'orders.create', ['resource' => 'order');
+```
+
 ### Extending values
 
 You may also build upon fully resolved language strings.