Skip to content

Commit 22c1505

Browse files
ashleyshawashleyshaw
committed
docs: create complete documentation structure and add i18n workflow
- Copy complete documentation structure from single-block scaffold - Create config/ directory with all tool documentation - Consolidate WP-scripts docs into single config/wp-scripts.md - Create comprehensive TESTING.md, AGENTS.md, and WORKFLOWS.md - Add i18n workflow for automated POT generation and validation - Create reports/ directory with STYLELINT-MIGRATION.md - Update .distignore to exclude dev files (docs/, reports/, bin/, etc.) - Add comprehensive documentation section to README.md - Establish consistent docs structure across all scaffolds This brings multi-block plugin scaffold documentation up to parity with the other two scaffolds.
1 parent fe0e803 commit 22c1505

33 files changed

+10117
-13
lines changed

‎.distignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,13 @@ yarn-error.log*
110110
# Build scripts
111111
bin/
112112

113+
# Documentation and reports (dev only)
114+
docs/
115+
reports/
116+
117+
# Development containers
118+
.devcontainer/
119+
113120
# Git hooks
114121
.husky/
115122

‎.github/workflows/i18n.yml‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Internationalization (i18n) Workflow
2+
# Generates translation template (POT) files and validates i18n implementation
3+
#
4+
# Features:
5+
# - Automatic POT file generation from PHP and JavaScript
6+
# - JSON translation file generation for JavaScript
7+
# - i18n validation and best practices checks
8+
# - Automated POT file updates on push to main/develop
9+
10+
name: Internationalization
11+
12+
on:
13+
push:
14+
branches: [main, develop]
15+
paths:
16+
- '**.php'
17+
- '**.js'
18+
- '**.jsx'
19+
- 'src/**'
20+
- 'inc/**'
21+
- 'package.json'
22+
pull_request:
23+
branches: [main, develop]
24+
paths:
25+
- '**.php'
26+
- '**.js'
27+
- '**.jsx'
28+
- 'src/**'
29+
- 'inc/**'
30+
workflow_dispatch:
31+
32+
permissions:
33+
contents: write
34+
pull-requests: write
35+
36+
env:
37+
TEXT_DOMAIN: '{{textdomain}}'
38+
POT_FILE: 'languages/{{slug}}.pot'
39+
40+
jobs:
41+
validate-i18n:
42+
name: Validate Internationalization
43+
runs-on: ubuntu-latest
44+
steps:
45+
- name: Checkout code
46+
uses: actions/checkout@v4
47+
48+
- name: Setup Node.js
49+
uses: actions/setup-node@v4
50+
with:
51+
node-version: '20'
52+
cache: 'npm'
53+
54+
- name: Setup PHP
55+
uses: shivammathur/setup-php@v2
56+
with:
57+
php-version: '8.1'
58+
tools: composer, wp-cli
59+
60+
- name: Install dependencies
61+
run: |
62+
npm ci
63+
composer install --prefer-dist --no-progress
64+
65+
- name: Check for hardcoded strings in source files
66+
run: |
67+
echo "## i18n Validation Report" >> $GITHUB_STEP_SUMMARY
68+
echo "" >> $GITHUB_STEP_SUMMARY
69+
70+
# Check for common hardcoded string patterns in all plugin folders
71+
HARDCODED=$(grep -r -E '>[[:space:]]*[A-Z][a-z]+[[:space:]<]' src/ inc/ templates/ parts/ patterns/ --include="*.js" --include="*.jsx" --include="*.php" --include="*.html" || true)
72+
73+
if [ -n "$HARDCODED" ]; then
74+
echo "⚠️ **Potential hardcoded strings found:**" >> $GITHUB_STEP_SUMMARY
75+
echo "" >> $GITHUB_STEP_SUMMARY
76+
echo '```' >> $GITHUB_STEP_SUMMARY
77+
echo "$HARDCODED" >> $GITHUB_STEP_SUMMARY
78+
echo '```' >> $GITHUB_STEP_SUMMARY
79+
echo "" >> $GITHUB_STEP_SUMMARY
80+
echo "::warning::Potential hardcoded strings found in source files. Consider using translation functions."
81+
else
82+
echo "✅ No obvious hardcoded strings detected" >> $GITHUB_STEP_SUMMARY
83+
fi
84+
85+
- name: Validate text domain usage
86+
run: |
87+
# Check for incorrect text domain usage
88+
WRONG_DOMAIN=$(grep -r -E "__\(|_e\(|_x\(|_n\(|esc_html__|esc_attr__" . \
89+
--include="*.php" \
90+
--exclude-dir=vendor \
91+
--exclude-dir=node_modules \
92+
| grep -v "'${{ env.TEXT_DOMAIN }}'" \
93+
| grep -v "// phpcs:" \
94+
|| true)
95+
96+
if [ -n "$WRONG_DOMAIN" ]; then
97+
echo "⚠️ **Incorrect text domain usage:**" >> $GITHUB_STEP_SUMMARY
98+
echo "" >> $GITHUB_STEP_SUMMARY
99+
echo "Expected text domain: \`${{ env.TEXT_DOMAIN }}\`" >> $GITHUB_STEP_SUMMARY
100+
echo "" >> $GITHUB_STEP_SUMMARY
101+
echo "::warning::Some translation functions may be using incorrect text domain"
102+
else
103+
echo "✅ Text domain usage correct" >> $GITHUB_STEP_SUMMARY
104+
fi
105+
106+
generate-pot:
107+
name: Generate POT Files
108+
runs-on: ubuntu-latest
109+
needs: validate-i18n
110+
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
111+
steps:
112+
- name: Checkout code
113+
uses: actions/checkout@v4
114+
with:
115+
token: ${{ secrets.GITHUB_TOKEN }}
116+
117+
- name: Setup Node.js
118+
uses: actions/setup-node@v4
119+
with:
120+
node-version: '20'
121+
cache: 'npm'
122+
123+
- name: Setup PHP
124+
uses: shivammathur/setup-php@v2
125+
with:
126+
php-version: '8.1'
127+
tools: wp-cli
128+
129+
- name: Install dependencies
130+
run: npm ci
131+
132+
- name: Create languages directory
133+
run: mkdir -p languages
134+
135+
- name: Generate POT from PHP files
136+
run: |
137+
wp i18n make-pot . languages/{{slug}}.pot \
138+
--slug={{slug}} \
139+
--domain={{textdomain}} \
140+
--exclude=node_modules,vendor,build,tests \
141+
--headers='{"Report-Msgid-Bugs-To":"{{supportUrl}}"}'
142+
143+
echo "✅ PHP POT file generated"
144+
145+
- name: Build JavaScript for translation extraction
146+
run: npm run build
147+
148+
- name: Generate POT from JavaScript files
149+
run: |
150+
# JavaScript strings are extracted during build via @wordpress/babel-plugin-makepot
151+
# Merge JavaScript POT with main POT if it exists
152+
if [ -f "languages/{{slug}}-js.pot" ]; then
153+
msgcat --use-first languages/{{slug}}.pot languages/{{slug}}-js.pot -o languages/{{slug}}.pot
154+
rm languages/{{slug}}-js.pot
155+
echo "✅ JavaScript strings merged into main POT"
156+
fi
157+
158+
- name: Generate JSON translation files
159+
run: |
160+
npm run makejson
161+
echo "✅ JSON translation files generated"
162+
163+
- name: Update POT file metadata
164+
run: |
165+
# Update POT-Creation-Date
166+
sed -i "s/POT-Creation-Date: .*/POT-Creation-Date: $(date -u +"%Y-%m-%d %H:%M+0000")/" languages/{{slug}}.pot
167+
168+
# Show statistics
169+
STRINGS=$(grep -c "^msgid " languages/{{slug}}.pot || echo "0")
170+
echo "📊 Total translatable strings: $STRINGS"
171+
172+
echo "## Translation Statistics" >> $GITHUB_STEP_SUMMARY
173+
echo "" >> $GITHUB_STEP_SUMMARY
174+
echo "- **Total strings:** $STRINGS" >> $GITHUB_STEP_SUMMARY
175+
echo "- **POT file:** \`${{ env.POT_FILE }}\`" >> $GITHUB_STEP_SUMMARY
176+
echo "- **Text domain:** \`${{ env.TEXT_DOMAIN }}\`" >> $GITHUB_STEP_SUMMARY
177+
178+
- name: Check for POT changes
179+
id: pot-changes
180+
run: |
181+
git add languages/
182+
if git diff --cached --quiet; then
183+
echo "changed=false" >> $GITHUB_OUTPUT
184+
echo "No changes to POT files"
185+
else
186+
echo "changed=true" >> $GITHUB_OUTPUT
187+
echo "POT files have been updated"
188+
fi
189+
190+
- name: Commit and push POT files
191+
if: steps.pot-changes.outputs.changed == 'true'
192+
run: |
193+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
194+
git config --local user.name "github-actions[bot]"
195+
git commit -m "chore(i18n): update translation template files [skip ci]"
196+
git push
197+
198+
- name: Upload POT as artifact
199+
uses: actions/upload-artifact@v4
200+
with:
201+
name: translation-template
202+
path: languages/*.pot
203+
retention-days: 30
204+
205+
test-translations:
206+
name: Test Translation Loading
207+
runs-on: ubuntu-latest
208+
needs: validate-i18n
209+
steps:
210+
- name: Checkout code
211+
uses: actions/checkout@v4
212+
213+
- name: Setup PHP
214+
uses: shivammathur/setup-php@v2
215+
with:
216+
php-version: '8.1'
217+
218+
- name: Test load_plugin_textdomain call
219+
run: |
220+
# Verify plugin loads translations correctly
221+
if grep -q "load_plugin_textdomain" {{slug}}.php; then
222+
echo "✅ load_plugin_textdomain() found in main plugin file"
223+
echo "✅ Plugin textdomain loading configured" >> $GITHUB_STEP_SUMMARY
224+
else
225+
echo "::error::load_plugin_textdomain() not found in main plugin file"
226+
exit 1
227+
fi
228+
229+
- name: Check for JavaScript translation setup
230+
run: |
231+
# Check for wp_set_script_translations usage
232+
if grep -r "wp_set_script_translations" . --include="*.php" --exclude-dir=vendor --exclude-dir=node_modules; then
233+
echo "✅ JavaScript translations configured"
234+
else
235+
echo "::warning::No wp_set_script_translations() calls found. JavaScript translations may not load."
236+
fi
237+
238+
summary:
239+
name: i18n Summary
240+
runs-on: ubuntu-latest
241+
needs: [validate-i18n, generate-pot, test-translations]
242+
if: always()
243+
steps:
244+
- name: Generate summary
245+
run: |
246+
echo "## Internationalization Workflow Complete" >> $GITHUB_STEP_SUMMARY
247+
echo "" >> $GITHUB_STEP_SUMMARY
248+
echo "| Task | Status |" >> $GITHUB_STEP_SUMMARY
249+
echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
250+
echo "| Validation | ${{ needs.validate-i18n.result }} |" >> $GITHUB_STEP_SUMMARY
251+
echo "| POT Generation | ${{ needs.generate-pot.result }} |" >> $GITHUB_STEP_SUMMARY
252+
echo "| Translation Tests | ${{ needs.test-translations.result }} |" >> $GITHUB_STEP_SUMMARY
253+
254+
if [[ "${{ needs.validate-i18n.result }}" == "failure" ]] || \
255+
[[ "${{ needs.test-translations.result }}" == "failure" ]]; then
256+
echo "" >> $GITHUB_STEP_SUMMARY
257+
echo "❌ **i18n checks failed**" >> $GITHUB_STEP_SUMMARY
258+
exit 1
259+
fi
260+
261+
echo "" >> $GITHUB_STEP_SUMMARY
262+
echo "✅ **All i18n checks passed**" >> $GITHUB_STEP_SUMMARY

‎README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,32 @@ This scaffold uses Mustache-style variables for customization:
174174
| `{{namespace}}` | Plugin namespace |
175175
| `{{textdomain}}` | Text domain |
176176

177+
## Documentation
178+
179+
Comprehensive documentation is available in the `docs/` directory:
180+
181+
- **[Build Process](docs/BUILD-PROCESS.md)** - Complete build system guide
182+
- **[Testing Guide](docs/TESTING.md)** - Running and writing tests
183+
- **[Internationalization](docs/INTERNATIONALIZATION.md)** - i18n and translation guide
184+
- **[Tool Configuration](docs/TOOL-CONFIGS.md)** - Linting, formatting, and build tools
185+
- **[Agents Guide](docs/AGENTS.md)** - AI agents and automation
186+
- **[Workflows Guide](docs/WORKFLOWS.md)** - CI/CD workflows documentation
187+
- **[API Reference](docs/API-REFERENCE.md)** - Plugin API documentation
188+
- **[Performance](docs/PERFORMANCE.md)** - Performance optimization guide
189+
- **[Security](docs/SECURITY-HEADERS.md)** - Security best practices
190+
191+
**Configuration Documentation** (`docs/config/`):
192+
193+
- [wp-scripts](docs/config/wp-scripts.md) - Complete @wordpress/scripts guide
194+
- [Webpack](docs/config/webpack.md) - Bundling configuration
195+
- [Babel](docs/config/babel.md) - JavaScript compilation
196+
- [ESLint](docs/config/eslint.md) - JavaScript linting
197+
- [Stylelint](docs/config/stylelint.md) - CSS/Sass linting
198+
- [PostCSS](docs/config/postcss.md) - CSS processing
199+
- [Jest](docs/config/jest.md) - Unit testing
200+
- [Playwright](docs/config/playwright.md) - E2E testing
201+
- [Prettier](docs/config/prettier.md) - Code formatting
202+
177203
## License
178204

179205
{{license}}

0 commit comments

Comments
 (0)