1  ---
  2  title: 'Country Templates'
  3  category: 'proposals'
  4  last_verified: '2026-02-15'
  5  related_files:
  6    - 'src/utils/spintax.js'
  7    - 'tests/spintax.test.js'
  8    - 'scripts/test-spintax.js'
  9  tags: ['country', 'templates', 'testing', 'api', 'ai', 'llm', 'email', 'sms']
 10  status: 'current'
 11  ---
 12  
 13  # Country-Based Spintax Templates - Implementation Summary
 14  
 15  ## ✅ What Was Done
 16  
 17  Converted all existing templates (Paul James, Dad, and System templates) to spintax format and organized them by country, merging with your preferred file structure.
 18  
 19  ## 📁 New File Structure
 20  
 21  ```
 22  data/templates/
 23  ├── US/
 24  │   ├── email.json (11 templates)
 25  │   └── sms.json (6 templates)
 26  └── AU/
 27      ├── email.json (11 templates)
 28      └── sms.json (6 templates)
 29  ```
 30  
 31  **Total: 34 templates** (28 email + 6 SMS) across 2 countries
 32  
 33  ## 🎯 Key Features
 34  
 35  ### 1. Country-Specific Localization
 36  
 37  **US Templates:**
 38  
 39  - American English spelling (analyzed, optimization)
 40  - Standard greetings (Hi, Hey)
 41  - Professional tone
 42  
 43  **AU Templates:**
 44  
 45  - Australian English spelling (analysed, optimisation, specialise)
 46  - Local greetings ("G'day" added to spintax options)
 47  - Same professional quality
 48  
 49  ### 2. Template Variables: Square Brackets
 50  
 51  All templates now use `[variable]` syntax (not `{variable}`):
 52  
 53  ```
 54  [firstname] - Contact's first name
 55  [domain] - Website domain
 56  [kwd] - Business keyword/industry
 57  [grade] - Conversion score grade (A+, B-, etc.)
 58  [score] - Numeric score (0-100)
 59  [reasoning] - Why the score is what it is
 60  [evidence] - Specific examples
 61  [primary_weakness] - Main conversion issue
 62  [impact] - Percentage impact estimate
 63  [industry] - Business industry
 64  [sender_id] - SMS sender identification
 65  [keyword] - Alternative to [kwd]
 66  ```
 67  
 68  ### 3. Spintax Variations
 69  
 70  All templates include multiple variations for:
 71  
 72  - **Greetings**: `{Hi|Hey|G'day}` (AU only for G'day)
 73  - **Action verbs**: `{analyzed|reviewed|examined}`
 74  - **CTAs**: `{Want details|Interested}?`
 75  - **Tone adjusters**: `{Quick heads up|Heads up|Quick update}`
 76  
 77  ### 4. Template Metadata
 78  
 79  Each template includes:
 80  
 81  - `id` - Unique identifier
 82  - `channel` - email or sms
 83  - `author` - Paul James, Dad, or System
 84  - `country` - US or AU
 85  - `subject_spintax` - Email subject (null for SMS)
 86  - `body_spintax` - Message body
 87  - `tone` - friendly, casual, professional, direct, etc.
 88  - `approach` - problem-solution, quick-win, educational, etc.
 89  - `tested` - A/B testing status (false by default)
 90  - `conversions` - Conversion count (0 by default)
 91  - `sends` - Send count (0 by default)
 92  
 93  ## 📊 Template Breakdown
 94  
 95  ### Email Templates
 96  
 97  **Paul James & Dad (Proven):**
 98  
 99  - 6 templates with battle-tested copy
100  - Multiple spintax variations per template
101  - Casual to professional tones
102  
103  **System (Dynamic):**
104  
105  - 5 templates with LLM-populated variables
106  - Integrates with scoring system
107  - Uses `[grade]`, `[evidence]`, `[reasoning]`, etc.
108  
109  ### SMS Templates
110  
111  **Paul James:**
112  
113  - 1 ultra-casual quick-win template
114  - Multiple opening variations
115  
116  **System:**
117  
118  - 5 templates with variable placeholders
119  - TCPA-compliant opt-out instructions
120  - Character-count optimized
121  
122  ## 🔧 Usage
123  
124  ### Load a Template
125  
126  ```javascript
127  import { loadAndSpinTemplate } from './src/utils/spintax.js';
128  
129  // Method 1: Specify country explicitly
130  const proposal = await loadAndSpinTemplate(
131    'email_pauljames_01',
132    { kwd: 'plumbing', firstname: 'Alice' },
133    'US'
134  );
135  
136  // Method 2: Use country/template format
137  const proposal2 = await loadAndSpinTemplate('AU/email_dad_01_au', {
138    kwd: 'electrician',
139    firstname: 'Bob',
140  });
141  
142  // Method 3: Default to US
143  const proposal3 = await loadAndSpinTemplate('sms_pauljames_01', { firstname: 'Charlie' });
144  
145  console.log(proposal.subject); // "is your plumbing site doing its job?"
146  console.log(proposal.body); // Full spun email body
147  console.log(proposal.country); // "US"
148  ```
149  
150  ### CLI Testing
151  
152  ```bash
153  # List all templates for a country
154  node scripts/test-spintax.js --list US
155  node scripts/test-spintax.js --list AU
156  
157  # Test a specific template
158  node scripts/test-spintax.js US/email_pauljames_01 --count 5 --kwd plumbing
159  
160  # Test AU template with local terms
161  node scripts/test-spintax.js AU/email_dad_01_au --kwd "tradie services" --firstname "Bruce"
162  ```
163  
164  ## 🌍 Adding New Countries
165  
166  To add templates for a new country (e.g., UK, CA, NZ):
167  
168  1. **Create directory**: `data/templates/UK/`
169  2. **Copy base templates**: Use US or AU as starting point
170  3. **Localize**:
171     - Update spelling (e.g., UK uses "optimisation" like AU)
172     - Add local greetings (UK: "Cheers", CA: same as US, NZ: "Kia ora")
173     - Adjust currency references if needed
174     - Update country field in each template
175  4. **Update IDs**: Add country suffix (e.g., `email_dad_01_uk`)
176  
177  ## 📈 Analytics Integration
178  
179  Each template tracks:
180  
181  ```sql
182  -- Update after each send
183  UPDATE templates SET sends = sends + 1 WHERE id = 'email_pauljames_01';
184  
185  -- Update after conversion
186  UPDATE templates SET conversions = conversions + 1, tested = 1 WHERE id = 'email_pauljames_01';
187  
188  -- Query top performers by country
189  SELECT
190    country,
191    id,
192    author,
193    approach,
194    conversions,
195    sends,
196    ROUND(conversions * 100.0 / sends, 2) as conversion_rate
197  FROM templates
198  WHERE sends > 0
199  ORDER BY conversion_rate DESC;
200  ```
201  
202  ## 🚀 Benefits
203  
204  ### 1. Zero LLM Cost
205  
206  - Instant template loading
207  - No API latency
208  - Unlimited scale
209  
210  ### 2. Proven Copy
211  
212  - Battle-tested by Paul James & Dad
213  - Consistent voice and quality
214  - Predictable performance
215  
216  ### 3. Cultural Optimization
217  
218  - Country-specific language
219  - Local greetings and idioms
220  - Better resonance with recipients
221  
222  ### 4. Spam Avoidance
223  
224  - Every message unique via spintax
225  - No identical duplicates
226  - ESP-friendly variation
227  
228  ### 5. Easy A/B Testing
229  
230  - Track performance per template
231  - Compare authors (Paul vs Dad vs System)
232  - Optimize by country, tone, approach
233  
234  ## 🔍 Quality Improvements Made
235  
236  From the original templates:
237  
238  1. ✅ Fixed "lookers" → "customers" (awkward phrasing)
239  2. ✅ Standardized "C-minus" notation
240  3. ✅ Removed "a third" (not equivalent to 20-40%)
241  4. ✅ Consistent American/Australian spelling
242  5. ✅ Added blank lines between paragraphs (2026 best practice)
243  6. ✅ Fixed capitalization inconsistencies
244  7. ✅ Converted `{var}` → `[var]` for clarity
245  8. ✅ Added comprehensive spintax variations
246  
247  ## 📝 Next Steps
248  
249  ### Phase 1: Integration
250  
251  - Update `proposal-generator-v2.js` to use templates
252  - Add `template_id` to outreaches table
253  - Track template performance
254  
255  ### Phase 2: A/B Testing
256  
257  - Randomly assign templates per send
258  - Measure conversion rates
259  - Identify top performers by country/channel
260  
261  ### Phase 3: Hybrid Approach
262  
263  - Use templates for 80% of prospects (proven, fast, cheap)
264  - Use LLM for 20% (edge cases, deep personalization)
265  - Best of both worlds
266  
267  ### Phase 4: Template Expansion
268  
269  - Add more countries (UK, CA, NZ, IE)
270  - Create industry-specific templates
271  - Develop seasonal/promotional variations
272  
273  ## 📚 Documentation
274  
275  - **Spintax Guide**: `/../90-archive/spintax-templates.md`
276  - **Implementation**: `/../90-archive/template-implementation.md`
277  - **This Summary**: `/country-templates.md`
278  
279  ## 🧪 Testing
280  
281  All spintax tests pass:
282  
283  ```bash
284  npm test tests/spintax.test.js
285  # ✅ 23 tests passing
286  ```
287  
288  Template loading works for all countries:
289  
290  ```bash
291  # US template
292  node -e "import { loadAndSpinTemplate } from './src/utils/spintax.js'; ..."
293  
294  # AU template
295  # Works perfectly with G'day and Australian spelling
296  ```
297  
298  ## 💡 Example Output
299  
300  **US Email (email_pauljames_01):**
301  
302  ```
303  Subject: is your plumbing site doing its job?
304  
305  Hey!
306  
307  I was looking at your website earlier and noticed your homepage offer score
308  is about a C (don't worry — most local businesses are in that range).
309  
310  Nothing is "broken," but you're likely missing out on at least 20-40% more
311  leads just from the way your offer and call-to-action are structured above
312  the fold.
313  
314  I do Local Offer Fix Audits that break this down and show exactly what to
315  change for fast lead increases.
316  
317  It's a simple one-time service — takes me about 24 hours — and the audit
318  is yours to keep.
319  
320  Want me to send over what I found?
321  ```
322  
323  **AU Email (email_dad_01_au):**
324  
325  ```
326  Subject: what one homepage fix keeps customers longer on your site?
327  
328  G'day Bruce,
329  
330  I took a quick look at your homepage and spotted a few places where your
331  offer could convert better.
332  
333  You know, turn more visitors into warm leads... without any extra ad spend.
334  
335  I put together a simple breakdown.
336  
337  Want me to send it over?
338  ```
339  
340  **US SMS (sms_pauljames_01):**
341  
342  ```
343  Quick review of your site - spotted some areas where your offer could
344  convert better. I put together a quick breakdown. Want me to send it over?
345  
346  Reply STOP to opt out
347  ```
348  
349  ## 🎉 Summary
350  
351  - ✅ **34 templates** across US/AU
352  - ✅ **Square bracket** variables for clarity
353  - ✅ **Spintax variations** for uniqueness
354  - ✅ **Country localization** (spelling, greetings)
355  - ✅ **Analytics ready** (tested, conversions, sends)
356  - ✅ **Proven copy** from Paul James & Dad
357  - ✅ **Zero cost** instant generation
358  - ✅ **All tests passing**
359  
360  Ready to integrate into the proposal generator!