🌐 Translation Fetching API Guide
Project: InventarListen (ID: 96)
🎯 Purpose: This API is designed for optimal translation fetching with intelligent caching.
AI should make individual calls per page/area rather than downloading entire language files.
Use this instead of the general strings API for better performance and caching support.
⏰ Timezone: All timestamps are returned in Norwegian time (Europe/Oslo timezone).
📋 API Endpoint
GET
/api/v1/projects/96/translations/{language}/{area}
🔧 Parameters
| Parameter |
Type |
Required |
Description |
Examples |
| language |
string |
Yes |
Language code |
no, en, de, sv |
| area |
string |
Yes |
Area name |
admin, public |
| cache_key |
string |
No |
Cache validation key |
2603e36dcd4568210b8004423b098e9b |
| force_refresh |
boolean |
No |
Bypass cache |
true |
| log_read |
boolean |
No |
Log that AI has read translations |
true |
| client_id |
string |
No |
Unique identifier for the AI client |
ai-frontend-001 |
🚀 Quick Start Examples
1. Get Norwegian translations for admin area
GET https://la.deltascripts.com/api/v1/projects/96/translations/no/admin
2. Get English translations for public area
GET https://la.deltascripts.com/api/v1/projects/96/translations/en/public
3. Check for updates using cache key
GET https://la.deltascripts.com/api/v1/projects/96/translations/no/admin?cache_key=2603e36dcd4568210b8004423b098e9b
4. Force refresh (bypass cache)
GET https://la.deltascripts.com/api/v1/projects/96/translations/no/admin?force_refresh=true
5. Log AI read with client ID
GET https://la.deltascripts.com/api/v1/projects/96/translations/no/admin?log_read=true&client_id=ai-frontend-001
6. Check for updates and log read
GET https://la.deltascripts.com/api/v1/projects/96/translations/no/admin?cache_key=2603e36dcd4568210b8004423b098e9b&log_read=true&client_id=ai-frontend-001
💾 Caching Strategy
🎯 How Cache Key Works
The cache key is a unique hash generated from:
- Latest string update timestamp
- Latest translation update timestamp
- Total number of strings
- Number of approved translations
When any of these change, the cache key changes, indicating new data is available.
Step 1: Initial Request
Make your first request to get all translations:
GET /api/v1/projects/96/translations/no/admin
Response includes a cache_key in the cache_info section.
Step 2: Store Cache Key
Save the cache_key locally for future requests:
const cacheKey = response.cache_info.cache_key;
Step 3: Check for Updates
Include the cache key in subsequent requests:
GET /api/v1/projects/96/translations/no/admin?cache_key=${cacheKey}
Step 4: Handle Response
- HTTP 200: New data available, update your local cache
- HTTP 304: No changes, use your existing local cache
📊 Response Format
Success Response (HTTP 200)
{
"success": true,
"project": {
"id": 96,
"name": "InventarListen"
},
"language": "no",
"area": "admin",
"translations": [
{
"full_key": "admin.department.title",
"text": "Avdelinger",
"string_updated": "2025-08-24 18:30:07",
"translation_updated": "2025-08-24 18:30:07"
}
],
"statistics": {
"total_strings": 17,
"approved_translations": 17,
"missing_translations": 0,
"coverage_percentage": 100
},
"cache_info": {
"cache_key": "2603e36dcd4568210b8004423b098e9b",
"last_modified": "2025-08-24 18:30:59",
"string_last_updated": "2025-08-24 18:30:59",
"translation_last_updated": "2025-08-24 18:30:59"
}
}
Cache Hit Response (HTTP 304)
{
"success": true,
"cached": true,
"message": "No changes detected, use cached version",
"cache_key": "2603e36dcd4568210b8004423b098e9b",
"last_modified": "2025-08-24 18:30:59"
}
🤖 AI Implementation Guide
1. Per-Page Translation Loading
// Store translations per page/area
let translationCache = {};
let cacheKeys = {};
// Load translations for specific page/area when needed
async function loadPageTranslations(language, area) {
const cacheKey = cacheKeys[\`\${language}_\${area}\`];
if (cacheKey) {
// Check for updates first
const response = await fetch(\`/api/v1/projects/96/translations/\${language}/\${area}?cache_key=\${cacheKey}&log_read=true&client_id=\${clientId}\`);
if (response.status === 304) {
// No changes, use existing cache
return translationCache[\`\${language}_\${area}\`];
}
}
// Load fresh data (first time or cache miss)
const response = await fetch(\`/api/v1/projects/96/translations/\${language}/\${area}?log_read=true&client_id=\${clientId}\`);
const data = await response.json();
if (response.ok) {
translationCache[\`\${language}_\${area}\`] = data.translations;
cacheKeys[\`\${language}_\${area}\`] = data.cache_info.cache_key;
return data.translations;
}
}
2. Page-Specific Usage
// Load translations when entering a specific page
async function onPageLoad(pageArea) {
const translations = await loadPageTranslations('no', pageArea);
console.log(\`Loaded \${translations.length} translations for \${pageArea}\`);
// Apply translations to current page
applyTranslationsToPage(translations);
}
// Example usage:
onPageLoad('admin'); // For admin pages
onPageLoad('public'); // For public pages
onPageLoad('member'); // For member pages
3. Get Translation by Key
function getTranslation(fullKey, language = 'no', area = 'admin') {
const cacheKey = \`\${language}_\${area}\`;
const translations = translationCache[cacheKey] || [];
const translation = translations.find(t => t.full_key === fullKey);
return translation ? translation.text : fullKey; // Fallback to key if not found
}
// Usage examples:
const title = getTranslation('admin.department.title'); // Returns "Avdelinger"
const welcome = getTranslation('public.home.welcome'); // Returns "Velkommen"
🔄 Recommended Update Schedule
| Scenario |
Frequency |
Method |
| Page navigation |
Every page load |
Check cache key per area |
| Same page refresh |
Every refresh |
Check cache key for current area |
| Background sync |
Every 5-10 minutes |
Check cache key for active areas |
| Force refresh |
On user request |
force_refresh=true |
| After content updates |
Immediately |
force_refresh=true |
⚠️ Important Notes
- Only approved translations are returned - Draft translations are not included
- Fallback to English - If Norwegian translation is missing, English base_text is returned
- Full keys required - Use complete keys like "admin.department.title"
- Area-specific - Each area (admin, public, member) is fetched separately
- Cache key changes - Any update to strings or translations invalidates the cache
🎯 Per-Page Approach Benefits
✅ Why Load Per Page/Area?
- Efficient Loading: Only load translations needed for current page
- Faster Page Load: Smaller payload per request
- Better Cache Management: Cache only relevant translations
- Reduced Bandwidth: Avoid downloading unused translations
- Improved Performance: Faster initial page rendering
- Memory Efficient: Keep only active area translations in memory
📱 Typical Usage Flow:
- User navigates to admin page → Load admin translations
- User navigates to public page → Load public translations
- User refreshes page → Check cache key for current area
- Background sync → Update cache for active areas only
🔗 Related APIs
✅ Benefits of This Approach
- Optimal Performance: Only fetch data when it changes
- Reduced Bandwidth: HTTP 304 responses use minimal data
- Real-time Updates: Cache key changes immediately when content updates
- Offline Support: Local cache works without internet
- Scalable: Works efficiently with large translation sets
Generated for Project InventarListen (ID: 96) on 2025-12-23 18:38:51