Skip to content

Commit c1b8f42

Browse files
ashleyshawashleyshaw
committed
docs: restructure documentation and add i18n workflow
- 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 for summaries and migration reports - Move SETUP-SUMMARY.md and STYLELINT-MIGRATION.md to reports/ - Update .distignore to exclude dev files (docs/, reports/, bin/, etc.) - Add comprehensive documentation section to README.md - Update TOOL-CONFIGS.md references to consolidated docs - Improve discoverability of all documentation BREAKING CHANGE: WP-scripts documentation consolidated from 3 files to 1
1 parent efc0cc4 commit c1b8f42

File tree

13 files changed

+1918
-947
lines changed

13 files changed

+1918
-947
lines changed

‎.distignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ coverage/
99
artifacts/
1010
test-results/
1111
playwright-report/
12+
bin/
13+
docs/
14+
reports/
15+
.devcontainer/
1216
*.log
1317
*.lock
1418
.DS_Store

‎.github/workflows/i18n.yml‎

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

‎README.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -227,8 +227,34 @@ Please read our [Contributing Guidelines](CONTRIBUTING.md) for more details.
227227

228228
## Support
229229

230-
- Documentation: [Full documentation]({{docs_url}})
231-
- Internationalization: [i18n Guide](docs/INTERNATIONALIZATION.md)
230+
### Documentation
231+
232+
Comprehensive documentation is available in the `docs/` directory:
233+
234+
- **[Build Process](docs/BUILD-PROCESS.md)** - Complete build system guide
235+
- **[Testing Guide](docs/TESTING.md)** - Running and writing tests
236+
- **[Internationalization](docs/INTERNATIONALIZATION.md)** - i18n and translation guide
237+
- **[Tool Configuration](docs/TOOL-CONFIGS.md)** - Linting, formatting, and build tools
238+
- **[Agents Guide](docs/AGENTS.md)** - AI agents and automation
239+
- **[Workflows Guide](docs/WORKFLOWS.md)** - CI/CD workflows documentation
240+
- **[API Reference](docs/API-REFERENCE.md)** - Theme API documentation
241+
- **[Performance](docs/PERFORMANCE.md)** - Performance optimization guide
242+
- **[Security](docs/SECURITY-HEADERS.md)** - Security best practices
243+
244+
**Configuration Documentation** (`docs/config/`):
245+
246+
- [wp-scripts](docs/config/wp-scripts.md) - Complete @wordpress/scripts guide
247+
- [Webpack](docs/config/webpack.md) - Bundling configuration
248+
- [Babel](docs/config/babel.md) - JavaScript compilation
249+
- [ESLint](docs/config/eslint.md) - JavaScript linting
250+
- [Stylelint](docs/config/stylelint.md) - CSS/Sass linting
251+
- [PostCSS](docs/config/postcss.md) - CSS processing
252+
- [Jest](docs/config/jest.md) - Unit testing
253+
- [Playwright](docs/config/playwright.md) - E2E testing
254+
- [Prettier](docs/config/prettier.md) - Code formatting
255+
256+
### Community Support
257+
232258
- Issues: [GitHub Issues]({{theme_repo_url}}/issues)
233259
- Community: [WordPress.org Support](https://wordpress.org/support/theme/{{theme_slug}})
234260

0 commit comments

Comments
 (0)