django-altified 0.1.0__tar.gz

django_altified-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: django-altified
+Version: 0.1.0
+Summary: Django SDK for syncing model content with Altified translations.
+Author: Altified
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Django>=4.2
+Requires-Dist: requests>=2.31
+
+# django-altified
+
+Django SDK for syncing configured model fields to Altified and reading translated values from Django cache.
+
+## Install
+
+```bash
+pip install django-altified
+```
+
+## Configure
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "django_altified",
+]
+
+ALTIFIED_API_KEY = "altified_..."
+ALTIFIED_API_URL = "https://your-altified-domain.com/api/v1"
+```
+
+The API key points to a Altified project, so the SDK does not need the project default or target languages in Django settings. Configure those languages in the Altified dashboard.
+
+At runtime the SDK uses Django active language, or an explicit language passed to `translate_field`, as the requested locale. Altified validates that locale against the project connected to the API key and returns the source text when the requested locale is the project default language.
+
+Create `altified.py` beside `manage.py`:
+
+```python
+from shop.models import Product
+
+TRANSLATIONS = {
+    Product: {
+        "fields": ["name", "description"],
+    }
+}
+```
+
+Use the safe helper first:
+
+```python
+from django_altified import translate_field, translate_fields
+
+name = translate_field(product, "name")
+copy = translate_fields(product, ["name", "description"])
+```
+
+Optionally expose the webhook endpoint:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("altified/", include("django_altified.urls")),
+]
+```

django_altified-0.1.0/README.md

@@ -0,0 +1,56 @@
+# django-altified
+
+Django SDK for syncing configured model fields to Altified and reading translated values from Django cache.
+
+## Install
+
+```bash
+pip install django-altified
+```
+
+## Configure
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "django_altified",
+]
+
+ALTIFIED_API_KEY = "altified_..."
+ALTIFIED_API_URL = "https://your-altified-domain.com/api/v1"
+```
+
+The API key points to a Altified project, so the SDK does not need the project default or target languages in Django settings. Configure those languages in the Altified dashboard.
+
+At runtime the SDK uses Django active language, or an explicit language passed to `translate_field`, as the requested locale. Altified validates that locale against the project connected to the API key and returns the source text when the requested locale is the project default language.
+
+Create `altified.py` beside `manage.py`:
+
+```python
+from shop.models import Product
+
+TRANSLATIONS = {
+    Product: {
+        "fields": ["name", "description"],
+    }
+}
+```
+
+Use the safe helper first:
+
+```python
+from django_altified import translate_field, translate_fields
+
+name = translate_field(product, "name")
+copy = translate_fields(product, ["name", "description"])
+```
+
+Optionally expose the webhook endpoint:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("altified/", include("django_altified.urls")),
+]
+```

django_altified-0.1.0/django_altified/__init__.py

@@ -0,0 +1,3 @@
+from .translate import translate_field, translate_fields
+
+__all__ = ["translate_field", "translate_fields"]

django_altified-0.1.0/django_altified/apps.py

@@ -0,0 +1,18 @@
+from django.apps import AppConfig
+
+
+class AltifiedConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_altified"
+
+    def ready(self):
+        from django.conf import settings
+
+        from .descriptors import install_descriptors
+        from .registry import registry
+        from .signals import connect_signals
+
+        registry.load()
+        if getattr(settings, "ALTIFIED_AUTO_TRANSLATE", True):
+            install_descriptors(registry)
+        connect_signals(registry)

django_altified-0.1.0/django_altified/cache.py

@@ -0,0 +1,17 @@
+from django.conf import settings
+from django.core.cache import cache
+
+
+def make_key(source_key, language):
+    prefix = getattr(settings, "ALTIFIED_CACHE_PREFIX", "altified")
+    return f"{prefix}:{source_key}:{language}"
+
+
+def get_translation(source_key, language):
+    return cache.get(make_key(source_key, language))
+
+
+def set_translation(source_key, language, text, timeout=None):
+    if timeout is None:
+        timeout = getattr(settings, "ALTIFIED_CACHE_TIMEOUT", None)
+    cache.set(make_key(source_key, language), text, timeout=timeout)

django_altified-0.1.0/django_altified/client.py

@@ -0,0 +1,55 @@
+import logging
+
+import requests
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+
+class AltifiedClient:
+    def __init__(self, api_key=None, api_url=None, timeout=None):
+        self.api_key = api_key or getattr(settings, "ALTIFIED_API_KEY", "")
+        self.api_url = (api_url or getattr(settings, "ALTIFIED_API_URL", "http://localhost:8000/api/v1")).rstrip("/")
+        self.timeout = timeout or getattr(settings, "ALTIFIED_TIMEOUT", 5)
+
+    @property
+    def headers(self):
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "django-altified/0.1.0",
+        }
+
+    def enabled(self):
+        return bool(self.api_key)
+
+    def post_sources(self, sources):
+        if not self.enabled() or not sources:
+            return None
+        return self._post("/sources/batch/", {"sources": sources})
+
+    def resolve(self, locale, sources):
+        if not self.enabled() or not sources:
+            return None
+        return self._post("/translations/resolve/", {"locale": locale, "sources": sources})
+
+    def heartbeat(self):
+        if not self.enabled():
+            return None
+        return self._post("/heartbeat/", {"kind": "secret"})
+
+    def _post(self, path, payload):
+        url = f"{self.api_url}{path}"
+        response = requests.post(url, json=payload, headers=self.headers, timeout=self.timeout)
+        response.raise_for_status()
+        return response.json()
+
+
+def safe_call(method, *args, **kwargs):
+    try:
+        return method(*args, **kwargs)
+    except requests.RequestException as exc:
+        if getattr(settings, "ALTIFIED_RAISE_ERRORS", False):
+            raise
+        logger.warning("Altified request failed: %s", exc)
+        return None

django_altified-0.1.0/django_altified/descriptors.py

@@ -0,0 +1,52 @@
+from .translate import translate_fields
+
+
+class TranslatedFieldDescriptor:
+    cache_attr = "_altified_translated_fields"
+
+    def __init__(self, field_name, original_descriptor, fields_for_model):
+        self.field_name = field_name
+        self.original_descriptor = original_descriptor
+        self.fields_for_model = tuple(fields_for_model)
+
+    def __get__(self, instance, owner=None):
+        if instance is None:
+            return self
+        cached = getattr(instance, self.cache_attr, None)
+        if cached is None:
+            cached = self._translate_instance(instance)
+            setattr(instance, self.cache_attr, cached)
+        if self.field_name in cached:
+            return cached[self.field_name]
+        return self._get_original(instance)
+
+    def __set__(self, instance, value):
+        if hasattr(instance, self.cache_attr):
+            delattr(instance, self.cache_attr)
+        if hasattr(self.original_descriptor, "__set__"):
+            self.original_descriptor.__set__(instance, value)
+            return
+        instance.__dict__[self.field_name] = value
+
+    def _translate_instance(self, instance):
+        raw_getters = {}
+        for field_name in self.fields_for_model:
+            descriptor = getattr(instance.__class__, field_name, None)
+            if isinstance(descriptor, TranslatedFieldDescriptor):
+                raw_getters[field_name] = descriptor._get_original
+        return translate_fields(instance, self.fields_for_model, raw_getters=raw_getters)
+
+    def _get_original(self, instance):
+        if hasattr(self.original_descriptor, "__get__"):
+            return self.original_descriptor.__get__(instance, instance.__class__)
+        return instance.__dict__.get(self.field_name)
+
+
+def install_descriptors(registry):
+    for model in registry.models():
+        fields = registry.fields_for(model)
+        for field_name in fields:
+            current = getattr(model, field_name, None)
+            if isinstance(current, TranslatedFieldDescriptor):
+                continue
+            setattr(model, field_name, TranslatedFieldDescriptor(field_name, current, fields))

django_altified-0.1.0/django_altified/keys.py

@@ -0,0 +1,7 @@
+def model_label(model_or_instance):
+    meta = model_or_instance._meta
+    return f"{meta.app_label}.{meta.object_name}"
+
+
+def source_key(instance, field_name):
+    return f"db:{model_label(instance)}:{instance.pk}:{field_name}"

django_altified-0.1.0/django_altified/management/__init__.py

@@ -0,0 +1 @@
+

django_altified-0.1.0/django_altified/management/commands/__init__.py

@@ -0,0 +1 @@
+

django_altified-0.1.0/django_altified/management/commands/init_altified.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from django.conf import settings
+from django.core.management.base import BaseCommand, CommandError
+
+
+TEMPLATE = '''"""
+Altified translation configuration.
+
+Add models and fields that should sync with Altified.
+"""
+
+# from shop.models import Product
+
+TRANSLATIONS = {
+    # Product: {
+    #     "fields": ["name", "description"],
+    # },
+}
+'''
+
+
+class Command(BaseCommand):
+    help = "Create a starter altified.py configuration file."
+
+    def add_arguments(self, parser):
+        parser.add_argument("--force", action="store_true", help="Overwrite an existing altified.py file.")
+
+    def handle(self, *args, **options):
+        path = Path(settings.BASE_DIR) / "altified.py"
+        if path.exists() and not options["force"]:
+            raise CommandError(f"{path} already exists. Use --force to overwrite it.")
+        path.write_text(TEMPLATE, encoding="utf-8")
+        self.stdout.write(self.style.SUCCESS(f"Created {path}"))

django_altified-0.1.0/django_altified/registry.py

@@ -0,0 +1,55 @@
+import importlib
+import logging
+import os
+import sys
+
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+
+class TranslationRegistry:
+    def __init__(self):
+        self._models = {}
+        self.loaded = False
+
+    def load(self):
+        if self.loaded:
+            return
+        self.loaded = True
+        module_name = getattr(settings, "ALTIFIED_CONFIG_MODULE", "altified")
+        self._ensure_base_dir_importable()
+        try:
+            module = importlib.import_module(module_name)
+        except ModuleNotFoundError as exc:
+            if exc.name == module_name:
+                logger.info("Altified config module %s was not found.", module_name)
+                return
+            raise
+
+        translations = getattr(module, "TRANSLATIONS", {})
+        for model, config in translations.items():
+            fields = config.get("fields", []) if isinstance(config, dict) else config
+            self.register(model, fields)
+
+    def register(self, model, fields):
+        clean_fields = tuple(dict.fromkeys(fields or []))
+        if clean_fields:
+            self._models[model] = clean_fields
+
+    def fields_for(self, model):
+        return self._models.get(model, ())
+
+    def models(self):
+        return tuple(self._models.keys())
+
+    def _ensure_base_dir_importable(self):
+        base_dir = getattr(settings, "BASE_DIR", None)
+        if not base_dir:
+            return
+        base_dir = os.fspath(base_dir)
+        if base_dir not in sys.path:
+            sys.path.insert(0, base_dir)
+
+
+registry = TranslationRegistry()

django_altified-0.1.0/django_altified/signals.py

@@ -0,0 +1,50 @@
+import threading
+
+from django.conf import settings
+from django.db.models.signals import post_save
+
+from .client import AltifiedClient, safe_call
+from .keys import source_key
+
+
+def connect_signals(registry):
+    if getattr(settings, "ALTIFIED_DISABLE_SIGNALS", False):
+        return
+    for model in registry.models():
+        post_save.connect(sync_instance, sender=model, weak=False, dispatch_uid=f"altified.sync.{model._meta.label_lower}")
+
+
+def sync_instance(sender, instance, **kwargs):
+    if instance.pk is None:
+        return
+    from .registry import registry
+
+    fields = registry.fields_for(sender)
+    sources = []
+    for field_name in fields:
+        value = getattr(instance, field_name, None)
+        if value in (None, ""):
+            continue
+        sources.append(
+            {
+                "key": source_key(instance, field_name),
+                "text": str(value),
+                "context": {
+                    "model": sender._meta.label,
+                    "object_id": str(instance.pk),
+                    "field": field_name,
+                },
+            }
+        )
+    if not sources:
+        return
+    if getattr(settings, "ALTIFIED_SYNC_ASYNC", True):
+        thread = threading.Thread(target=_send_sources, args=(sources,), daemon=True)
+        thread.start()
+    else:
+        _send_sources(sources)
+
+
+def _send_sources(sources):
+    client = AltifiedClient()
+    safe_call(client.post_sources, sources)

django_altified-0.1.0/django_altified/translate.py

@@ -0,0 +1,87 @@
+from django.utils.translation import get_language
+
+from .cache import get_translation, set_translation
+from .client import AltifiedClient, safe_call
+from .keys import source_key
+
+
+def _field_source(instance, field_name, original):
+    key = source_key(instance, field_name)
+    return key, {
+        "key": key,
+        "text": str(original),
+        "context": {
+            "model": instance._meta.label,
+            "object_id": str(instance.pk),
+            "field": field_name,
+        },
+    }
+
+
+def _translation_text(response, key):
+    if not response:
+        return None
+    item = response.get("translations", {}).get(key)
+    if isinstance(item, dict):
+        return item.get("text")
+    if isinstance(item, str):
+        return item
+    return None
+
+
+def _original_value(instance, field_name, raw_getter=None):
+    if raw_getter:
+        return raw_getter(instance)
+    descriptor = getattr(instance.__class__, field_name, None)
+    getter = getattr(descriptor, "_get_original", None)
+    if getter:
+        return getter(instance)
+    return getattr(instance, field_name)
+
+
+def translate_fields(instance, field_names, language=None, defaults=None, raw_getters=None):
+    locale = language or get_language()
+    defaults = defaults or {}
+    raw_getters = raw_getters or {}
+    results = {}
+    pending = []
+    pending_by_key = {}
+
+    for field_name in field_names:
+        original = _original_value(instance, field_name, raw_getters.get(field_name))
+        if original in (None, ""):
+            results[field_name] = original
+            continue
+        if not locale:
+            results[field_name] = original
+            continue
+
+        key, source = _field_source(instance, field_name, original)
+        cached = get_translation(key, locale)
+        if cached is not None:
+            results[field_name] = cached
+            continue
+
+        pending.append(source)
+        pending_by_key[key] = (field_name, original)
+        results[field_name] = original if field_name not in defaults else defaults[field_name]
+
+    if not pending:
+        return results
+
+    client = AltifiedClient()
+    response = safe_call(client.resolve, locale, pending)
+    for key, (field_name, original) in pending_by_key.items():
+        translated = _translation_text(response, key)
+        if translated:
+            set_translation(key, locale, translated)
+            results[field_name] = translated
+        elif field_name not in defaults:
+            results[field_name] = original
+    return results
+
+
+def translate_field(instance, field_name, language=None, default=None, raw_getter=None):
+    defaults = {field_name: default} if default is not None else None
+    raw_getters = {field_name: raw_getter} if raw_getter else None
+    return translate_fields(instance, [field_name], language=language, defaults=defaults, raw_getters=raw_getters)[field_name]

django_altified-0.1.0/django_altified/urls.py

@@ -0,0 +1,7 @@
+from django.urls import path
+
+from .views import WebhookView
+
+urlpatterns = [
+    path("webhook/", WebhookView.as_view(), name="altified-webhook"),
+]

django_altified-0.1.0/django_altified/views.py

@@ -0,0 +1,45 @@
+import hashlib
+import hmac
+import json
+
+from django.conf import settings
+from django.http import JsonResponse
+from django.utils.decorators import method_decorator
+from django.views import View
+from django.views.decorators.csrf import csrf_exempt
+
+from .cache import set_translation
+
+
+def verify_signature(body, signature):
+    api_key = getattr(settings, "ALTIFIED_API_KEY", "")
+    if not api_key or not signature:
+        return False
+    expected = hmac.new(api_key.encode(), body, hashlib.sha256).hexdigest()
+    provided = signature.removeprefix("sha256=")
+    return hmac.compare_digest(expected, provided)
+
+
+@method_decorator(csrf_exempt, name="dispatch")
+class WebhookView(View):
+    def post(self, request):
+        if not verify_signature(request.body, request.headers.get("X-Altified-Signature", "")):
+            return JsonResponse({"detail": "Invalid Altified signature."}, status=403)
+        try:
+            payload = json.loads(request.body.decode("utf-8"))
+        except json.JSONDecodeError:
+            return JsonResponse({"detail": "Invalid JSON payload."}, status=400)
+
+        items = payload.get("translations")
+        if items is None:
+            items = [payload]
+        stored = 0
+        for item in items:
+            key = item.get("key")
+            language = item.get("language") or item.get("locale")
+            text = item.get("text")
+            if not key or not language or text is None:
+                continue
+            set_translation(key, language, text)
+            stored += 1
+        return JsonResponse({"stored": stored})

django_altified-0.1.0/django_altified.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: django-altified
+Version: 0.1.0
+Summary: Django SDK for syncing model content with Altified translations.
+Author: Altified
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Django>=4.2
+Requires-Dist: requests>=2.31
+
+# django-altified
+
+Django SDK for syncing configured model fields to Altified and reading translated values from Django cache.
+
+## Install
+
+```bash
+pip install django-altified
+```
+
+## Configure
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "django_altified",
+]
+
+ALTIFIED_API_KEY = "altified_..."
+ALTIFIED_API_URL = "https://your-altified-domain.com/api/v1"
+```
+
+The API key points to a Altified project, so the SDK does not need the project default or target languages in Django settings. Configure those languages in the Altified dashboard.
+
+At runtime the SDK uses Django active language, or an explicit language passed to `translate_field`, as the requested locale. Altified validates that locale against the project connected to the API key and returns the source text when the requested locale is the project default language.
+
+Create `altified.py` beside `manage.py`:
+
+```python
+from shop.models import Product
+
+TRANSLATIONS = {
+    Product: {
+        "fields": ["name", "description"],
+    }
+}
+```
+
+Use the safe helper first:
+
+```python
+from django_altified import translate_field, translate_fields
+
+name = translate_field(product, "name")
+copy = translate_fields(product, ["name", "description"])
+```
+
+Optionally expose the webhook endpoint:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("altified/", include("django_altified.urls")),
+]
+```

django_altified-0.1.0/django_altified.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+django_altified/__init__.py
+django_altified/apps.py
+django_altified/cache.py
+django_altified/client.py
+django_altified/descriptors.py
+django_altified/keys.py
+django_altified/registry.py
+django_altified/signals.py
+django_altified/translate.py
+django_altified/urls.py
+django_altified/views.py
+django_altified.egg-info/PKG-INFO
+django_altified.egg-info/SOURCES.txt
+django_altified.egg-info/dependency_links.txt
+django_altified.egg-info/requires.txt
+django_altified.egg-info/top_level.txt
+django_altified/management/__init__.py
+django_altified/management/commands/__init__.py
+django_altified/management/commands/init_altified.py

django_altified-0.1.0/django_altified.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_altified-0.1.0/django_altified.egg-info/requires.txt

@@ -0,0 +1,2 @@
+Django>=4.2
+requests>=2.31

django_altified-0.1.0/django_altified.egg-info/top_level.txt

@@ -0,0 +1 @@
+django_altified

django_altified-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-altified"
+version = "0.1.0"
+description = "Django SDK for syncing model content with Altified translations."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "Django>=4.2",
+  "requests>=2.31",
+]
+authors = [
+  { name = "Altified" }
+]
+classifiers = [
+  "Framework :: Django",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.setuptools.packages.find]
+include = ["django_altified*"]

django_altified-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+