# Te Reo Māori Standards for Language Learning Templates
**Document Version:** 1.0
**Date:** October 6, 2025
**Author:** Alan William Preston
**Purpose:** Standardized utilities for handling Te Reo Māori in interactive web-based language learning templates
---
## 1. Overview
This document provides standardized JavaScript functions for handling Te Reo Māori text in interactive language learning templates. These utilities address the common challenge of accepting user input that may not include proper macrons (tohutō) over vowels.
**Language:** Te Reo Māori (Māori Language of Aotearoa New Zealand)
**Writing System:** Latin alphabet with macrons
**Target Learners:** Non-native speakers and heritage learners
---
## 2. Te Reo Māori Orthography
### 2.1 The Māori Alphabet
Te Reo Māori uses a subset of the Latin alphabet:
**Consonants:** h, k, m, n, p, r, t, w, ng, wh
**Vowels:** a, e, i, o, u
**Total:** 10 consonants (including digraphs ng and wh) + 5 vowels = 15 letters
### 2.2 Macrons (Tohutō)
The macron (tohutō) is a diacritical mark placed over vowels to indicate a long vowel sound. It is critical for correct pronunciation and meaning.
| Vowel | With Macron | Example Word | Meaning | Without Macron | Different Meaning |
|-------|-------------|--------------|---------|----------------|-------------------|
| a | ā | kāinga | home, village | kainga | (not a word) |
| e | ē | whēkau | wedge | whekau | laughing owl |
| i | ī | mīharo | wonderful | miharo | admire |
| o | ō | kōrero | speak, story | korero | (not standard) |
| u | ū | kūmara | sweet potato | kumara | (variant spelling) |
### 2.3 Macron Representations
Users may input macrons in several ways:
| Standard | Description | Example | Alternative Numeric | Alternative Double Vowel |
|----------|-------------|---------|--------------------|-----------------------|
| ā | a with macron | Māori | a1 or a: | aa |
| ē | e with macron | Kēmu | e1 or e: | ee |
| ī | i with macron | tīpuna | i1 or i: | ii |
| ō | o with macron | kōrero | o1 or o: | oo |
| ū | u with macron | tūpuna | u1 or u: | uu |
**Note:** Double vowel convention (aa, ee, etc.) is sometimes used when macrons are unavailable, but this can be ambiguous as some words genuinely contain double vowels (e.g., "oo" in "poopoo").
### 2.4 Special Digraphs
**ng** - A single sound (velar nasal), not n + g
- Examples: tangata (person), whanau (family)
- Pronunciation: Like "ng" in "singer" (not "finger")
**wh** - Pronounced as 'f' in most dialects
- Examples: whānau (family), whakapapa (genealogy)
- Pronunciation: Usually [f], sometimes [ɸ] or [hw] in some dialects
### 2.5 Capitalization Rules
**Traditional:** No capitals except for proper names and beginning of sentences
**Modern Usage:**
- Proper nouns: Aotearoa, Tāmaki Makaurau (Auckland)
- Titles: Kaiako (teacher), Rangatira (chief)
- Beginning of sentences
---
## 3. Core Utility Functions
### 3.1 Basic Macron Normalization
```javascript
/**
* Normalizes Māori text to handle various macron input formats
* Removes macrons, converts double vowels, removes spaces for comparison
* @param {string} text - The Māori text to normalize
* @returns {string} - Normalized text in lowercase without macrons
*/
function normalizeMaori(text) {
return text.toLowerCase()
// Remove macrons from vowels
.replace(/ā/g, 'a')
.replace(/ē/g, 'e')
.replace(/ī/g, 'i')
.replace(/ō/g, 'o')
.replace(/ū/g, 'u')
// Convert double vowels to single (for alternative input)
.replace(/aa/g, 'a')
.replace(/ee/g, 'e')
.replace(/ii/g, 'i')
.replace(/oo/g, 'o')
.replace(/uu/g, 'u')
// Remove numeric indicators if used
.replace(/([aeiou])1/g, '$1')
.replace(/([aeiou]):/g, '$1')
// Remove spaces and hyphens for comparison
.replace(/[\s\-]/g, '')
.trim();
}
```
### 3.2 Macron-Preserving Normalization
```javascript
/**
* Normalizes Māori text while preserving macrons
* Converts double vowels to macrons, handles spacing
* @param {string} text - The Māori text to normalize
* @returns {string} - Normalized text with macrons preserved
*/
function normalizeMaoriWithMacrons(text) {
return text.toLowerCase()
// Convert double vowels to macrons (when appropriate)
.replace(/aa/g, 'ā')
.replace(/ee/g, 'ē')
.replace(/ii/g, 'ī')
.replace(/oo/g, 'ō')
.replace(/uu/g, 'ū')
// Convert numeric/colon notation to macrons
.replace(/a1/g, 'ā').replace(/a:/g, 'ā')
.replace(/e1/g, 'ē').replace(/e:/g, 'ē')
.replace(/i1/g, 'ī').replace(/i:/g, 'ī')
.replace(/o1/g, 'ō').replace(/o:/g, 'ō')
.replace(/u1/g, 'ū').replace(/u:/g, 'ū')
// Standardize spacing
.replace(/\s+/g, ' ')
.trim();
}
```
### 3.3 HTML Stripping Function
```javascript
/**
* Strips HTML tags from Māori text
* Useful for comparing user input against formatted content
* @param {string} html - HTML string
* @returns {string} - Plain text content without HTML
*/
function stripHTML(html) {
const temp = document.createElement('div');
temp.innerHTML = html;
return temp.textContent || temp.innerText || '';
}
```
### 3.4 Māori Text Comparison
```javascript
/**
* Compares two Māori strings with flexible matching
* @param {string} input - User input string
* @param {string} correct - Correct answer string
* @param {boolean} requireMacrons - If true, macrons must match; if false, ignores macrons
* @returns {boolean} - True if strings match according to rules
*/
function compareMaori(input, correct, requireMacrons = false) {
if (requireMacrons) {
// Normalize but preserve macrons
const normalizedInput = normalizeMaoriWithMacrons(input).replace(/\s/g, '');
const normalizedCorrect = normalizeMaoriWithMacrons(correct).replace(/\s/g, '');
return normalizedInput === normalizedCorrect;
} else {
// Remove macrons for comparison
const normalizedInput = normalizeMaori(input);
const normalizedCorrect = normalizeMaori(correct);
return normalizedInput === normalizedCorrect;
}
}
```
### 3.5 Universal Answer Checking Function
```javascript
/**
* Checks user answer against Māori text
* Accepts input with or without macrons (depending on requireMacrons setting)
* @param {string} userInput - What the user typed
* @param {string} correctMaori - Correct Māori answer (may have HTML)
* @param {boolean} requireMacrons - Whether to check macron accuracy
* @returns {boolean} - True if answer is correct
*/
function checkMaoriAnswer(userInput, correctMaori, requireMacrons = false) {
const cleanCorrect = stripHTML(correctMaori);
return compareMaori(userInput, cleanCorrect, requireMacrons);
}
```
### 3.6 Macron Detection
```javascript
/**
* Checks if text contains macrons
* Useful for determining user's input method
* @param {string} text - Text to check
* @returns {boolean} - True if macrons are present
*/
function hasMacrons(text) {
return /[āēīōū]/i.test(text);
}
```
### 3.7 Validation for Māori Characters
```javascript
/**
* Validates if text contains only valid Māori characters
* Māori alphabet: a, e, i, o, u, h, k, m, n, p, r, t, w (plus ng, wh)
* @param {string} text - Text to validate
* @returns {boolean} - True if text contains only valid Māori characters
*/
function isValidMaoriText(text) {
// Allow letters in Māori alphabet, macrons, spaces, hyphens, apostrophes
const maoriPattern = /^[aāeēiīoōuūhkmnprtwng\s\-']+$/i;
return maoriPattern.test(text);
}
```
---
## 4. Complete Utility Object (Recommended Implementation)
```javascript
/**
* MaoriUtils - Comprehensive utilities for Te Reo Māori templates
* Usage: MaoriUtils.checkAnswer(userInput, correctMaori)
*/
const MaoriUtils = {
/**
* Normalizes Māori text (removes macrons)
*/
normalizeMaori: function(text) {
return text.toLowerCase()
.replace(/ā/g, 'a')
.replace(/ē/g, 'e')
.replace(/ī/g, 'i')
.replace(/ō/g, 'o')
.replace(/ū/g, 'u')
.replace(/aa/g, 'a')
.replace(/ee/g, 'e')
.replace(/ii/g, 'i')
.replace(/oo/g, 'o')
.replace(/uu/g, 'u')
.replace(/([aeiou])1/g, '$1')
.replace(/([aeiou]):/g, '$1')
.replace(/[\s\-]/g, '')
.trim();
},
/**
* Normalizes Māori text (preserves/adds macrons)
*/
normalizeMaoriWithMacrons: function(text) {
return text.toLowerCase()
.replace(/aa/g, 'ā')
.replace(/ee/g, 'ē')
.replace(/ii/g, 'ī')
.replace(/oo/g, 'ō')
.replace(/uu/g, 'ū')
.replace(/a1/g, 'ā').replace(/a:/g, 'ā')
.replace(/e1/g, 'ē').replace(/e:/g, 'ē')
.replace(/i1/g, 'ī').replace(/i:/g, 'ī')
.replace(/o1/g, 'ō').replace(/o:/g, 'ō')
.replace(/u1/g, 'ū').replace(/u:/g, 'ū')
.replace(/\s+/g, ' ')
.trim();
},
/**
* Strips HTML tags from text
*/
stripHTML: function(html) {
const temp = document.createElement('div');
temp.innerHTML = html;
return temp.textContent || temp.innerText || '';
},
/**
* Compares Māori strings
*/
compareMaori: function(input, correct, requireMacrons = false) {
if (requireMacrons) {
const normalizedInput = this.normalizeMaoriWithMacrons(input).replace(/\s/g, '');
const normalizedCorrect = this.normalizeMaoriWithMacrons(correct).replace(/\s/g, '');
return normalizedInput === normalizedCorrect;
} else {
const normalizedInput = this.normalizeMaori(input);
const normalizedCorrect = this.normalizeMaori(correct);
return normalizedInput === normalizedCorrect;
}
},
/**
* Universal answer checker
*/
checkAnswer: function(userInput, correctMaori, requireMacrons = false) {
const cleanCorrect = this.stripHTML(correctMaori);
return this.compareMaori(userInput, cleanCorrect, requireMacrons);
},
/**
* Checks if text contains macrons
*/
hasMacrons: function(text) {
return /[āēīōū]/i.test(text);
},
/**
* Validates Māori characters
*/
isValidMaoriText: function(text) {
const maoriPattern = /^[aāeēiīoōuūhkmnprtwng\s\-']+$/i;
return maoriPattern.test(text);
},
/**
* Adds macrons to text based on common words (dictionary lookup)
* Note: This requires a dictionary; basic implementation shown
*/
addMacrons: function(text) {
// Basic common word replacements
const macronMap = {
'maori': 'māori',
'kia ora': 'kia ora', // no macrons
'whanau': 'whānau',
'aroha': 'aroha', // no macrons
'kaiako': 'kaiako', // no macrons
'kainga': 'kāinga',
'kumara': 'kūmara',
'tupuna': 'tūpuna',
'korero': 'kōrero'
};
let result = text.toLowerCase();
for (const [plain, macron] of Object.entries(macronMap)) {
const regex = new RegExp(plain, 'gi');
result = result.replace(regex, macron);
}
return result;
}
};
```
---
## 5. Implementation Examples
### 5.1 Basic Quiz Answer Checking (Ignore Macrons)
```javascript
// Beginner mode - accept answer with or without macrons
function checkQuizAnswer() {
const userInput = document.getElementById('quiz-input').value.trim();
const correctMaori = currentItem.maori; // e.g., "kōrero"
if (MaoriUtils.checkAnswer(userInput, correctMaori, false)) {
// Correct answer! (korero, kōrero, ko:rero all accepted)
showSuccessFeedback();
} else {
// Incorrect
showErrorFeedback();
}
}
```
### 5.2 Advanced Quiz (Require Correct Macrons)
```javascript
// Advanced mode - macrons must be correct
function checkQuizAnswerWithMacrons() {
const userInput = document.getElementById('quiz-input').value.trim();
const correctMaori = currentItem.maori;
if (MaoriUtils.checkAnswer(userInput, correctMaori, true)) {
// Correct with proper macrons!
showSuccessFeedback();
} else if (MaoriUtils.checkAnswer(userInput, correctMaori, false)) {
// Right word, wrong macrons
showPartialFeedback("Correct word, but check your macrons (tohutō)!");
} else {
// Completely incorrect
showErrorFeedback();
}
}
```
### 5.3 Flexible Input Acceptance
```javascript
// Accept multiple input formats
function checkFlexibleAnswer() {
const userInput = document.getElementById('quiz-input').value.trim();
const correctMaori = currentItem.maori; // "whānau"
// Check if user typed with macrons, double vowels, or plain
// All these should work: whānau, whaanau, wha:nau, whanau
if (MaoriUtils.checkAnswer(userInput, correctMaori, false)) {
showSuccessFeedback();
// Optional: Give bonus praise if they used macrons correctly
if (MaoriUtils.hasMacrons(userInput)) {
showBonusFeedback("Ka pai! You used the macrons correctly!");
}
} else {
showErrorFeedback();
}
}
```
### 5.4 Validation Before Checking
```javascript
// Validate input before checking answer
function checkWithValidation() {
const userInput = document.getElementById('quiz-input').value.trim();
const correctMaori = currentItem.maori;
// First check if input contains only valid Māori characters
if (!MaoriUtils.isValidMaoriText(userInput)) {
showWarning("Please use only Māori alphabet characters (a-u, h, k, m, n, p, r, t, w)");
return;
}
if (MaoriUtils.checkAnswer(userInput, correctMaori, false)) {
showSuccessFeedback();
} else {
showErrorFeedback();
}
}
```
---
## 6. Testing Matrix
### 6.1 Test Cases for normalizeMaori()
| Input | Expected Output | Notes |
|-------|----------------|-------|
| Māori | maori | Macron removed |
| maori | maori | Already normalized |
| Maaori | maori | Double vowel converted |
| Ma:ori | maori | Colon notation removed |
| whānau | whanau | Macron removed |
| whaanau | whanau | Double vowel converted |
| Kia ora | kiaora | Space removed |
| tūpuna | tupuna | Macron removed |
### 6.2 Test Cases for normalizeMaoriWithMacrons()
| Input | Expected Output | Notes |
|-------|----------------|-------|
| Maaori | māori | Double vowel to macron |
| Ma:ori | māori | Colon to macron |
| maori | maori | No change (ambiguous) |
| whaanau | whānau | Double vowel to macron |
| tuupuna | tūpuna | Double vowel to macron |
### 6.3 Test Cases for compareMaori()
| Input (User) | Correct Answer | requireMacrons=false | requireMacrons=true |
|--------------|----------------|---------------------|-------------------|
| korero | kōrero | ✓ Match | ✗ No match |
| kōrero | kōrero | ✓ Match | ✓ Match |
| ko:rero | kōrero | ✓ Match | ✓ Match |
| koorero | kōrero | ✓ Match | ✓ Match |
| Kia Ora | kia ora | ✓ Match | ✓ Match |
---
## 7. Common Edge Cases
### 7.1 Genuine Double Vowels vs Macrons
Some words have genuine double vowels (rare):
- **oo** in some words is actually two o sounds, not ō
- Solution: Context-dependent; for most learning templates, treat double vowels as macron alternatives
### 7.2 Digraph Handling
**ng** - Keep as single unit
- "tangata" should not be split as "ta-n-gata"
- Treat as one consonant sound
**wh** - Keep as single unit
- "whānau" is three syllables: whā-na-u
- Not four: w-hā-na-u
### 7.3 Proper Nouns and Place Names
Many place names have specific spellings:
- **Aotearoa** - New Zealand (long o: ō is often omitted in practice)
- **Tāmaki Makaurau** - Auckland
- **Te Ika-a-Māui** - North Island
- **Te Waipounamu** - South Island
### 7.4 Compound Words and Hyphens
Some words use hyphens:
- **ika-a-Māui** (fish of Māui)
- **mā-tea** (pale, white)
For comparison, consider removing hyphens or being flexible.
### 7.5 Modern Loanwords
Te Reo Māori has borrowed and adapted words:
- **Hēmi** (James)
- **Hoani** (John)
- **Pāpā** (father, from Papa)
- **Māmā** (mother, from Mama)
---
## 8. Cultural Considerations
### 8.1 Importance of Correct Pronunciation
Macrons are not decorative - they change meaning:
- **keke** = cake
- **kēkē** = armpit
- **kaka** = to swear (also the name of a parrot)
- **kākā** = parrot (specifically)
### 8.2 Respect for Te Reo
When creating learning materials:
- Use correct macrons in your source material
- Provide cultural context where appropriate
- Acknowledge that Te Reo Māori is a living, evolving language
- Be aware of dialectal variations
### 8.3 Grammar Notes
Te Reo Māori grammar differs significantly from English:
- **Verb-Subject-Object** word order (VSO)
- Particles: ko, ka, i, ki, etc. are essential
- No verb "to be" in the English sense
- Plurals often indicated by context or particles, not word endings
---
## 9. Font and Display Recommendations
### 9.1 Font Stack for Te Reo Māori
Recommended font-family ensuring proper macron display:
```css
font-family: "Noto Sans", "Arial", "Helvetica Neue", "Helvetica", sans-serif;
```
### 9.2 Macron Display in CSS
Ensure macrons render correctly:
```css
.maori-text {
font-feature-settings: "kern" 1;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
```
### 9.3 Input Field Configuration
For text inputs accepting Māori:
```html
<input type="text"
lang="mi"
placeholder="Type in Te Reo Māori"
class="maori-input">
```
```css
.maori-input {
font-family: "Noto Sans", "Arial", sans-serif;
font-size: 16px;
}
```
---
## 10. Quick Reference: Copy-Paste Code Block
```javascript
/* ============================================
TE REO MĀORI UTILITIES
Version 1.0 - Copy this into your templates
============================================ */
const MaoriUtils = {
normalizeMaori: function(text) {
return text.toLowerCase()
.replace(/ā/g, 'a')
.replace(/ē/g, 'e')
.replace(/ī/g, 'i')
.replace(/ō/g, 'o')
.replace(/ū/g, 'u')
.replace(/aa/g, 'a')
.replace(/ee/g, 'e')
.replace(/ii/g, 'i')
.replace(/oo/g, 'o')
.replace(/uu/g, 'u')
.replace(/([aeiou])1/g, '$1')
.replace(/([aeiou]):/g, '$1')
.replace(/[\s\-]/g, '')
.trim();
},
stripHTML: function(html) {
const temp = document.createElement('div');
temp.innerHTML = html;
return temp.textContent || temp.innerText || '';
},
checkAnswer: function(userInput, correctMaori, requireMacrons = false) {
const cleanCorrect = this.stripHTML(correctMaori);
const normalizedInput = this.normalizeMaori(userInput);
const normalizedCorrect = this.normalizeMaori(cleanCorrect);
return normalizedInput === normalizedCorrect;
},
hasMacrons: function(text) {
return /[āēīōū]/i.test(text);
},
isValidMaoriText: function(text) {
return /^[aāeēiīoōuūhkmnprtwng\s\-']+$/i.test(text);
}
};
/* ============================================
END TE REO MĀORI UTILITIES
============================================ */
```
---
## 11. Difficulty Levels Recommendation
### Level 1: Beginner (Tauira)
- Accept answers without macrons
- Focus on vocabulary recognition
- Provide macron reference chart
### Level 2: Intermediate (Kaiwhakaako)
- Encourage macron use but accept without
- Give feedback when macrons are missing
- Teach significance of macrons
### Level 3: Advanced (Mātanga)
- Require correct macrons
- Test in context (sentences, not just words)
- Include cultural and grammatical context
---
## 12. Common Vocabulary for Testing
| Māori | English | Notes |
|-------|---------|-------|
| kia ora | hello, thank you | No macrons |
| aroha | love | No macrons |
| whānau | family | One macron |
| kōrero | speak, story | One macron |
| tūpuna | ancestors | One macron |
| kāinga | home, village | One macron |
| maunga | mountain | No macrons |
| moana | ocean | No macrons |
| whenua | land, country | No macrons |
| tangata | person | No macrons |
| whakapapa | genealogy | One macron |
| mātauranga | knowledge | Two macrons |
| kaitiaki | guardian | No macrons |
| marae | communal area | No macrons |
| hui | gathering | No macrons |
---
## 13. Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-10-06 | Initial document creation |
---
## 14. Related Resources
- **Māori Dictionary:** [maoridictionary.co.nz](https://maoridictionary.co.nz/)
- **Te Aka Māori Dictionary:** [teomaori.co.nz](https://www.teomaori.co.nz/)
- **Māori Language Commission (Te Taura Whiri i te Reo Māori):** [tetaurawhiri.govt.nz](https://www.tetaurawhiri.govt.nz/)
- **Unicode for Māori Macrons:**
- ā = U+0101
- ē = U+0113
- ī = U+012B
- ō = U+014D
- ū = U+016B
---
## 15. Notes for Template Development
1. **Always provide correct macrons** in source material
2. **Accept flexible input** from learners (especially beginners)
3. **Educate about macrons** - explain why they matter
4. **Test cross-platform** - ensure macrons display on all devices
5. **Consider mobile keyboards** - macron input varies by device
6. **Provide alternative input methods** - double vowels, numeric notation
7. **Cultural sensitivity** - acknowledge Te Reo Māori as a taonga (treasure)
8. **Dialectal variations** - Be aware some words have regional differences
9. **Grammar support** - Consider adding grammar notes for context
10. **Pronunciation guides** - Consider adding audio where possible
---
**Kia kaha! (Be strong/Keep going!)**
**End of Document**