docs: add example for source files caching between workflow runs (#298)

Author: andrii-bodnar

docs/EXAMPLES.md

@@ -5,6 +5,7 @@
 - [No-crowdin.yml configuration](#no-crowdinyml-configuration)
 - [Upload sources only](#upload-sources-only)
 - [Upload sources to the branch in Crowdin](#upload-sources-to-the-branch-in-crowdin)
+- [Caching source files for faster uploads](#caching-source-files-for-faster-uploads)
 - [Download only translations without pushing to a branch](#download-only-translations-without-pushing-to-a-branch)
 - [Download Bundle](#download-bundle)
 - [Advanced Pull Request configuration](#advanced-pull-request-configuration)
@@ -189,6 +190,53 @@ jobs:
 
 Note that the value of the `crowdin_branch_name` is `env.BRANCH_NAME` - this is the name of the current branch on which the action is running.
 
+### Caching source files for faster uploads
+
+The Crowdin CLI supports a `--cache` parameter for the `upload sources` command that stores source file checksums locally. This allows the CLI to only upload files that have changed, significantly reducing upload time for large projects.
+
+> **Note**
+> The cache feature is experimental. For any feedback, visit [Crowdin CLI Discussions](https://github.com/crowdin/crowdin-cli/discussions).
+
+To persist the cache between workflow runs, use the `actions/cache` action to save and restore the cache file located at `~/.crowdin/cache.json`:
+
+```yaml
+name: Crowdin Action
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  crowdin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Cache Crowdin source files
+        uses: actions/cache@v4
+        with:
+          path: ~/.crowdin/cache.json
+          key: ${{ runner.os }}-crowdin-cache-${{ github.ref_name }}-${{ hashFiles('**/crowdin.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-crowdin-cache-${{ github.ref_name }}-
+
+      - name: Crowdin push
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: true
+          upload_translations: false
+          download_translations: false
+          upload_sources_args: '--cache'
+        env:
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+```
+
+The cache key includes the current branch name and the `crowdin.yml` file hash, so each branch maintains its own cache and the cache will be invalidated when your Crowdin configuration changes. The `restore-keys` ensures that even if the exact key doesn't match (e.g., when `crowdin.yml` changes), a previous cache for the same branch will be restored, which is useful for incremental updates.
+
+Make sure to pass the `--cache` argument to the `upload_sources_args` option to use the cache.
+
 ### Download only translations without pushing to a branch
 
 It's possible to just download the translations without creating a PR immediately. It allows you to post-process the downloaded translations and create a PR later.