More i18n docs

stellarwp · Jul 19, 2023 · 4674cfa · 4674cfa
1 parent dbf6566
commit 4674cfa
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 27 deletions.
diff --git a/.puprc-defaults b/.puprc-defaults
@@ -26,9 +26,7 @@
         "file_format": "%textdomain%-%wp_locale%.%format%",
         "formats": ["po", "mo"],
         "filter": {
-            "translation_sets": false,
-            "minimum_percentage": 30,
-            "waiting_strings": false
+            "minimum_percentage": 30
         }
     },
     "paths": {

diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@ This is a CLI utility built by [StellarWP](https://stellarwp.com) for running pr
   * [Install globally as a git clone](/docs/installation.md#install-globally-as-a-git-clone) - another good option for your system.
 * [Configuration](/docs/configuration.md)
   * [Glob patterns](/docs/glob-patterns.md) - for your `.distfiles` and `.distignore` files.
+  * [Internationalization (i18n)](/docs/i18n.md)
 * [Commands](/docs/commands.md)
   * [`pup build`](/docs/commands.md#pup-build)
   * [`pup check`](/docs/commands.md#pup-check)

diff --git a/docs/commands.md b/docs/commands.md
@@ -86,8 +86,8 @@ composer -- pup check:tbd
 | `fail_method`     | **Optional.** How the check should fail. Defaults to `error`.                                |
 | `fail_method_dev` | **Optional.** How the check should fail when running with `--dev`. Defaults to `warn`. |
 | `dirs`                | **Optional.** An array of directories to scan. Defaults to `['src']`.                                                      |
-| `skip_directories`    | **Optional.** A pipe delimited list of directories to skip. Defaults can be seen in [`.puprc-defaults`](/.puprc-defaults). |
-| `skip_files`          | **Optional.** A pipe delimited list of files to skip. Defaults can be seen in [`.puprc-defaults`](/.puprc-defaults).       |
+| `skip_directories`    | **Optional.** A pipe delimited list of directories to skip. Defaults can be seen in [`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults). |
+| `skip_files`          | **Optional.** A pipe delimited list of files to skip. Defaults can be seen in [`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults).       |
 
 
 ### `pup check:version-conflict`
@@ -131,7 +131,7 @@ composer -- pup clean
 ## `pup get-version`
 Gets your project's version number.
 
-This command will use the first [version file](/docs/configuration.md#paths-versions) declared in your `.puprc` file to get the version number.
+This command will use the first [version file](https://github.com/stellarwp/pup/blob/main/docs/configuration.md#paths-versions) declared in your `.puprc` file to get the version number.
 If you haven't provided a version file, the version will be `unknown`.
 
 ### Usage
@@ -190,27 +190,10 @@ a bare minimum, you must specify the following:
 }
 ```
 
-If you wish to specify multiple `i18n` configs, being sure to override the `path` value so that the second config
-will download language files to an alternate location:
-
-```json
-"i18n": [
-    {
-        "slug": "the-slug-used-in-glotpress",
-        "textdomain": "my-textdomain",
-        "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable"
-    },
-    {
-        "path": "some-other-path/lang",
-        "slug": "the-slug-used-in-glotpress",
-        "textdomain": "my-textdomain",
-        "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable"
-    }
-]
-```
-
 By default, the config settings for `i18n` inherit defaults from the `i18n_defaults` values in the
-[`.puprc-defaults`](/.puprc-defaults) found within `pup`.
+[`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults) found within `pup`.
+
+For more information on the available options, see the [i18n documentation](https://github.com/stellarwp/pup/blob/main/docs/i18n.md).
 
 ## `pup info`
 Gets `pup` details for the current project.
@@ -270,7 +253,7 @@ composer -- pup package <version> [--dev]
 ## `pup zip`
 Runs the full `pup` set of commands to create a zip file.
 
-This command is a wrapper command for the whole zipping process. You can see its [flow of commands](/docs/flow.md) for 
+This command is a wrapper command for the whole zipping process. You can see its [flow of commands](https://github.com/stellarwp/pup/blob/main/docs/flow.md) for 
 more information on which commands it runs and when.
 
 ### Usage

diff --git a/docs/i18n.md b/docs/i18n.md
@@ -0,0 +1,55 @@
+# Internationalization (i18n)
+
+The `pup i18n` command can be used do fetch language files from a GlotPress instance for your project. To enable this
+command, you must configure the `i18n` section of your `.puprc` file.
+
+## The bare minimum
+
+```json
+{
+    "i18n": {
+        "slug": "the-slug-used-in-glotpress",
+        "textdomain": "my-textdomain",
+        "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable"
+    }
+}
+```
+
+By default, the config settings for `i18n` inherit defaults from the `i18n_defaults` values in the
+[`.puprc-defaults`](/.puprc-defaults) found within `pup`.
+
+## Fetching from multiple sources
+
+If you wish to specify multiple `i18n` configs, being sure to override the `path` value so that the second config
+will download language files to an alternate location:
+
+```json
+{
+    "i18n": [
+        {
+            "slug": "the-slug-used-in-glotpress",
+            "textdomain": "my-textdomain",
+            "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable"
+        },
+        {
+            "path": "some-other-path/lang",
+            "slug": "the-slug-used-in-glotpress",
+            "textdomain": "my-textdomain",
+            "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable"
+        }
+    ]
+}
+```
+
+## All options
+
+| Config option               | Type | Description                                                                                                                                       |
+|-----------------------------|---|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| `file_format`               | `string` | The format of the file name for each language file that is downloaded. See [`.puprc-defaults`](/.puprc-defaults) for the default value.           |
+| `filter`                    | `object` | This is the containing object for filters used in fetching language files.                                                                        |
+| `filter.minimum_percentage` | `boolean` | The percentage of strings that must be translated in order to download the file. See [`.puprc-defaults`](/.puprc-defaults) for the default value. |
+| `formats` | `array` | The array of file formats to download. Defaults to `['mo', 'po']`.                                                                                |
+| `path` | `string` | The path to download the language files to. Defaults to `lang`.                                                                                   |
+| `slug` | `string` | The slug used in GlotPress to identify the project.                                                                                               |
+| `textdomain` | `string` | The textdomain used in the project.                                                                                                               |
+| `url` | `string` | The URL to the GlotPress API endpoint.                                                                                                            |