🔤 Translator Guide

Quick tips for translators and developers working with string constants

💡 Quick Start: Use the suggest API to get valid constant names, then use the AI-optimized propose API to create new strings with intelligent feedback.

🤖 AI Integration Ready: This guide is optimized for Replit.com and other AI platforms. All endpoints include full URLs and comprehensive feedback.

📋 Naming Convention

All string constants follow this pattern: area.section.string

💡 Note: The entire area.section.string is the constant name. The "string" part is just the variable identifier.

🚀 New Projects: When you create a new project, it automatically comes with default areas and sections ready to use!

Areas

public - Public pages
member - Member-only pages
admin - Admin pages
mail - Email templates

✅ Default Areas: New projects automatically include admin, public, and member areas.

Sections

login - Login pages
profile - User profiles
settings - Settings pages
search - Search functionality
... and more

✅ Default Sections: New projects include common sections like dashboard, home, about, contact, etc.

String (Variable Name)

Max 8 characters
Lowercase letters only (a-z)
No numbers or special characters
Examples: welcome, savebtn, edittext

📋 Default Project Structure

When you create a new project, it automatically comes with this structure:

🎯 Default Areas & Sections

🔐 Admin Area

dashboard - Admin dashboard
login - Admin login
settings - Admin settings

🌐 Public Area

home - Homepage
about - About page
contact - Contact page

👤 Member Area

profile - User profile
messages - User messages
preferences - User preferences

💡 Tip: You can add more areas and sections, or rename existing ones using the Areas & Sections management APIs.

🚀 API Workflow

1. Check for Similar Strings (NEW)

Before creating a new string, check if similar strings already exist to avoid duplicates. Area filtering is recommended to avoid confusion between different contexts (e.g., admin vs public areas):

POST https://la.deltascripts.com/api/v1/projects/{id}/strings:find-similar

Request Body:

{
  "text": "Welcome to our website!",
  "area": "public",
  "limit": 10,
  "include_partial": true
}

Response:

{
   "success": true,
   "search_text": "Welcome to our website!",
   "search_area": "public",
   "total_found": 3,
  "results": {
    "exact_matches": [
      {
        "id": 123,
        "key": "welcome",
        "base_text": "Welcome to our website!",
        "area_name": "public",
        "section_name": "home",
        "match_type": "exact_match",
        "similarity_score": 100
      }
    ],
    "partial_matches": [
      {
        "id": 124,
        "key": "welcome_msg",
        "base_text": "Welcome message",
        "area_name": "public",
        "section_name": "login",
        "match_type": "contains_new",
        "similarity_score": 80
      }
    ]
  },
  "recommendations": {
    "exact_match_found": "Use existing string instead of creating duplicate",
    "suggested_action": "use_existing"
  },
  "suggested_alternatives": [
    {
      "action": "use_existing",
      "string_id": 123,
      "full_key": "public.home.welcome",
      "base_text": "Welcome to our website!",
      "api_endpoints": {
        "view_string": "GET https://la.deltascripts.com/api/v1/projects/64/strings/123"
      }
    }
  ]
}

2. Get Suggestions

Use the suggest API to get valid constant names based on your text:

GET https://la.deltascripts.com/api/v1/projects/{id}/strings:suggest

Query Parameters:

text - Your text (e.g., "Welcome to our site")
area - Area context (public, member, admin)
section - Section context (login, profile, etc.)
limit - Max suggestions (default: 10, max: 50)

Example:

GET https://la.deltascripts.com/api/v1/projects/64/strings:suggest?text=Welcome%20message&area=public§ion=home&limit=10

💡 URL Encoding: Spaces and special characters in the text parameter should be URL-encoded:

Welcome message → Welcome%20message
Hello, world! → Hello%2C%20world%21
User's profile → User%27s%20profile

Note: The area and section parameters use simple lowercase names and don't need encoding.

Response:

{
  "suggestions": [
    {
      "constant": "welcome",
      "full_key": "public.home.welcome",
      "length": 7
    },
    {
      "constant": "welcomebtn",
      "full_key": "public.home.welcomebtn",
      "length": 8
    }
  ],
  "rules": {
    "max_length": 8,
    "allowed_chars": "a-z only",
    "format": "area.section.string"
  }
}

3. Create New String (AI-Optimized)

Use the AI-optimized propose API for intelligent feedback and duplicate detection:

POST https://la.deltascripts.com/api/v1/projects/{id}/strings:ai-propose

Request Body:

{
  "area": "public",
  "section": "home", 
  "base_text": "Welcome to our website!",
  "suggested_key": "welcome"  // Optional - AI will generate if not provided
}

Success Response:

{
  "success": true,
  "message": "String created successfully",
  "data": {
    "id": 123,
    "key": "welcome",
    "full_key": "public.home.welcome",
    "base_text": "Welcome to our website!",
    "area": "public",
    "section": "home",
    "status": "active",
    "created_at": "2025-01-27 10:30:00",
    "created_by": "John Doe"
  },
  "similar_strings_found": null,
  "api_endpoints": {
    "view_string": "GET https://la.deltascripts.com/api/v1/projects/64/strings/123",
    "update_string": "PUT https://la.deltascripts.com/api/v1/projects/64/strings/123",
    "delete_string": "DELETE https://la.deltascripts.com/api/v1/projects/64/strings/123",
    "list_all_strings": "GET https://la.deltascripts.com/api/v1/projects/64/strings"
  }
}

Enhanced Duplicate Detection Response:

{
  "success": false,
  "error": "String key already exists",
  "duplicate_info": {
    "id": 123,
    "key": "welcome",
    "existing_text": "Welcome to our website!",
    "status": "active",
    "created_at": "2025-01-27 10:30:00"
  },
  "suggestions": {
    "use_existing": "The string already exists with ID 123",
    "update_existing": "Use PUT /api/v1/projects/64/strings/123 to update the existing string",
    "different_key": "Try a different key or use the suggest endpoint to get alternatives"
  },
  "api_endpoints": {
    "suggest_alternatives": "GET https://la.deltascripts.com/api/v1/projects/64/strings:suggest?text=Welcome to our website!&area=public§ion=home",
    "update_existing": "PUT https://la.deltascripts.com/api/v1/projects/64/strings/123",
    "view_existing": "GET https://la.deltascripts.com/api/v1/projects/64/strings/123"
  }
}

Success with Similar Strings Warning:

{
  "success": true,
  "message": "String created successfully",
  "warning": "⚠️ Exact or case-insensitive match found! Consider using existing string instead.",
  "data": {
    "id": 456,
    "key": "welcome",
    "full_key": "public.home.welcome",
    "base_text": "Welcome to our website!",
    "area": "public",
    "section": "home",
    "status": "active",
    "created_at": "2025-01-27 10:30:00",
    "created_by": "John Doe"
  },
  "similar_strings_found": {
    "exact_matches": [
      {
        "id": 123,
        "key": "welcome",
        "base_text": "Welcome to our website!",
        "area_name": "public",
        "section_name": "login",
        "match_type": "exact_match"
      }
    ],
    "partial_matches": [],
    "total_found": 1,
    "recommendations": {
      "exact_match_found": "Consider using existing string instead of creating duplicate",
      "suggested_action": "delete_new_use_existing"
    }
  },
  "suggested_alternatives": [
    {
      "action": "use_existing",
      "string_id": 123,
      "full_key": "public.login.welcome",
      "base_text": "Welcome to our website!",
      "api_endpoint": "GET https://la.deltascripts.com/api/v1/projects/64/strings/123"
    }
  ]
}

🤖 AI Benefits:

Automatic Key Generation: If no key provided, AI generates one from the text
Advanced Duplicate Detection: Finds exact matches, case-insensitive matches, and similar text across entire project
Smart Suggestions: Provides alternative actions and API endpoints with full URLs
Similarity Scoring: Ranks matches by relevance (100% for exact, 95% for case-insensitive, etc.)
Reuse Recommendations: Suggests using existing strings instead of creating duplicates
Cross-Area Detection: Finds similar strings across different areas and sections

💡 Common Use Cases

🔐 Login Page

Area: public
Section: login
Common Strings: welcome, username, password, loginbtn

👤 User Profile

Area: member
Section: profile
Common Strings: editbtn, savebtn, name, email

⚙️ Admin Settings

Area: admin
Section: settings
Common Strings: savebtn, cancelbtn, title, desc

🔍 Search Function

Area: public
Section: search
Common Strings: searchbtn, placeholder, results

📧 Email Templates

Area: mail
Section: welcome, reset, notification
Common Strings: subject, greeting, body, footer

📧 Email Examples

Welcome Email: mail.welcome.subject, mail.welcome.greeting
Password Reset: mail.reset.subject, mail.reset.body
Notifications: mail.notify.subject, mail.notify.body

🤖 AI/Replit Integration Guide

Optimized workflow for AI platforms and Replit.com integration with simple project-based authentication:

🔓 Simple AI Access: No complex authentication needed! Just use the project ID in the URL. Perfect for Replit.com and other AI platforms.

🚀 Simple AI Access (No Authentication Required)

Step 1: Get Project Info

curl -X POST "https://la.deltascripts.com/api/v1/projects/64/strings/ai" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "info"
  }'

Step 2: Find Similar Strings

curl -X POST "https://la.deltascripts.com/api/v1/projects/64/strings/ai" \
   -H "Content-Type: application/json" \
   -d '{
     "action": "find_similar",
     "text": "Welcome to our website!",
     "area": "public",
     "limit": 10
   }'

Step 3: Create String

curl -X POST "https://la.deltascripts.com/api/v1/projects/64/strings/ai" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "area": "public",
    "section": "home",
    "base_text": "Welcome to our website!",
    "suggested_key": "welcome"
  }'

Step 3: Handle Responses

Success (201): String created, use provided API endpoints for next actions
Duplicate (409): String exists, use suggested endpoints to update or view existing
Validation Error (400): Check required fields and try again
Not Found (404): Area/section doesn't exist, check available options

⚠️ Important for AI:

Always check the success field in responses
Use the api_endpoints provided in responses for next actions
Handle duplicate detection gracefully - update existing strings instead of creating duplicates
Use the similar_strings_found field to avoid content duplication
Include proper Authorization headers with Bearer tokens

🎯 Best Practices

⚠️ Important Rules:

Always use the suggest API first to get valid string names
String names must be 8 characters or less
Only use lowercase letters a-z
No numbers, underscores, or special characters
Choose descriptive but short names

🔗 Quick Reference

Action	API Call	Purpose
Get Suggestions	`GET https://la.deltascripts.com/api/v1/projects/{id}/strings:suggest`	Get valid string names for your text
Create String (AI)	`POST https://la.deltascripts.com/api/v1/projects/{id}/strings:ai-propose`	Create new string with intelligent feedback and duplicate detection
Create String (Standard)	`POST https://la.deltascripts.com/api/v1/projects/{id}/strings:propose`	Create new string with chosen string name
List Strings	`GET https://la.deltascripts.com/api/v1/projects/{id}/strings`	View all strings in project
Filter Strings	`GET https://la.deltascripts.com/api/v1/projects/{id}/strings?area=public§ion=login`	Filter strings by area and section
Update Base Text	`PUT https://la.deltascripts.com/api/v1/projects/{id}/strings/{key}`	Update English source text of a single string (use string key like 'login_welcome', not full path)
Bulk Update Base Text	`POST https://la.deltascripts.com/api/v1/projects/{id}/strings:update`	Update English source text of multiple strings (use string keys like 'login_welcome', not full paths)
Delete String	`DELETE https://la.deltascripts.com/api/v1/projects/{id}/strings/{stringId}`	Permanently delete a string and all its translations (requires admin access)

✅ Success Tips:

Start with the suggest API to avoid naming errors
Use descriptive text in your suggest API calls
Choose the most appropriate area and section
Keep string names short but meaningful
Test your API calls before production use

← Back to API Documentation