docs: update README with examples

Author: ramsey

README.md

@@ -49,7 +49,124 @@ composer require skillshare/formatphp
 
 ## Usage
 
-TBA
+The following example shows a complete working implementation of FormatPHP.
+
+```php
+use FormatPHP\Config;
+use FormatPHP\FormatPHP;
+use FormatPHP\Intl;
+use FormatPHP\Message;
+use FormatPHP\MessageCollection;
+
+// Translated messages in Spanish with matching IDs to what you declared.
+$messagesInSpanish = new MessageCollection([
+    new Message('hello', '¡Hola {name}! Hoy es {ts, date, ::yyyyMMdd}.'),
+]);
+
+$config = new Config(
+    // Locale of the application (or of the user using the application).
+    locale: new Intl\Locale('es'),
+);
+
+$formatphp = new FormatPHP(
+    config: $config,
+    messages: $messagesInSpanish,
+);
+
+echo $formatphp->formatMessage([
+    'id' => 'hello',
+    'defaultMessage' => 'Hello, {name}! Today is {ts, date, ::yyyyMMdd}.',
+], [
+    'name' => 'Arwen',
+    'ts' => time(),
+]);
+```
+
+### Using MessageLoader to Load Messages
+
+We also provide a message loader to load translation strings from locale files
+that have been generated by your translation management system.
+
+```php
+use FormatPHP\MessageLoader;
+
+$messageLoader = new MessageLoader(
+    // The path to your locale JSON files (i.e., en.json, es.json, etc.).
+    messagesDirectory: '/path/to/app/locales',
+    // The configuration object created earlier.
+    config: $config,
+);
+
+$messagesInSpanish = $messageLoader->loadMessages();
+```
+
+This example assumes a directory of locale JSON files located at
+`/path/to/app/locales`, which includes an `en.json` file with these
+contents:
+
+```json
+{
+  "hello": {
+    "defaultMessage": "Hello, {name}! Today is {ts, date, ::yyyyMMdd}."
+  }
+}
+```
+
+and an `es.json` file with these contents:
+
+```json
+{
+  "hello": {
+    "defaultMessage": "¡Hola {name}! Hoy es {ts, date, ::yyyyMMdd}."
+  }
+}
+```
+
+The message loader uses a fallback method to choose locales. In this example,
+if the user's locale is `es-419` (i.e., Spanish appropriate for the Latin
+America and Caribbean region), the fallback method will choose `es.json` for the
+messages.
+
+### Using the Console Command To Extract Messages
+
+The `formatphp extract` console command helps you extract messages from your
+application source code, saving them to JSON files that your translation
+management system can use.
+
+```shell
+./vendor/bin/formatphp extract --out-file=locales/en.json 'src/**/*.php' 'src/**/*.phtml'
+```
+
+In order for message extraction to function properly, we have a few rules that
+must be followed (see comments inline in the following example):
+
+```php
+// The method name must be exactly `formatMessage`. (see note below)
+// The name of the variable does not matter.
+$formatphp->formatMessage(
+    // The message descriptor should be an array literal.
+    [
+        'id' => 'hello', // ID (if provided) should be a string literal.
+        'description' => 'Message to translators', // Description should be a string literal.
+        'defaultMessage' => 'My name is {name}', // Message should be a string literal.
+    ],
+    [
+        'name' => $userName,
+    ],
+);
+```
+
+At least one of `id` or `defaultMessage` must be present.
+
+> ℹ️ If you wish to use a different function name (e.g., maybe you wish to wrap
+> this method call in a Closure, etc.), you may do so, but you must provide the
+> `--additional-function-names` option to the `formatphp extract` console
+> command. This option takes a comma-separated list of function names for the
+> extractor to parse.
+>
+> ```
+> --additional-function-names='formatMessage, myCustomFormattingFunction'
+> ```
 
 ## Contributing