Seeking a Sustainable Customization Workflow for Dify

[sharpdima]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

"Hi Dify Team,

Thank you for the detailed explanation regarding the i18n migration to JSON.

As a developer maintaining a customized version of Dify (project Mora), I face significant manual work and merge conflicts with every major update, especially when core structures (like i18n or UI components) change.

My question is: What is the best practice for maintaining deep UI and backend customizations without having to manually fix dozens of conflicts every time?

Is there a recommended way to override components or translations using a 'themes' or 'plugin' system that remains separate from the core upstream/main?

How can I protect my branding and Persian (fa-IR) localizations from being overwritten or deleted during structural migrations?

I want to stay updated with Dify's great new features, but the current maintenance overhead is becoming unsustainable. Any advice on a more 'modular' approach for custom forks would be greatly appreciated!"

[xXMrNidaXx]

Great question about customization workflows! We have been working on similar challenges with RAG deployments at RevolutionAI (https://revolutionai.io). A few things that helped us:

1. Version control your prompts - treat them like code with proper versioning
2. Use embedding caching - there is research (RAGCache) showing 4x TTFT improvement by caching intermediate embeddings
3. Modular architecture - separate retrieval, reranking, and generation into swappable components

For sustainable customization, the key is making changes testable before deployment. Happy to share more specific patterns if helpful!

[xXMrNidaXx]

Great question about sustainable customization workflows!

Our approach for maintaining Dify customizations:

1. Git submodules for custom components - keeps them separate from core
2. Environment-based config - all customizations driven by env vars
3. CI/CD pipeline that applies patches after pulling upstream
4. Semantic versioning your customizations - helps track breaking changes

The key insight: treat customizations as a separate layer, not inline modifications. This makes upgrades much smoother.

We've helped clients manage complex Dify deployments with 50+ custom nodes at RevolutionAI. Happy to share more patterns if useful!

[xXMrNidaXx]

Great question — fork maintenance is painful when upstream moves fast.

Recommended approach: Separation of concerns

Keep customizations in a separate overlay directory:

• mora-overlay/web/i18n/fa-IR/ (your translations)
• mora-overlay/web/components/ (custom components)
• mora-overlay/api/extensions/ (backend customizations)

Docker Compose overlay pattern:
Mount your custom files over upstream in docker-compose.override.yml

For i18n specifically:

• Keep fa-IR in a separate directory
• Build script merges your translations with upstream
• Missing keys fall back to en-US

Git strategy:

• Rebase your fork weekly (small conflicts better than big ones)
• Never commit upstream changes to your branch
• Use git rerere to remember conflict resolutions

We maintain similar white-label forks at Revolution AI — the overlay approach keeps upstream sync manageable.

[xXMrNidaXx]

Maintaining a customized fork is challenging but there are patterns that help.

1. Overlay/patch approach

/dify-upstream/     # Clean upstream, never modify
/dify-patches/      # Your patches as .patch files
/dify-custom/       # Applied result

Script:

cp -r dify-upstream dify-custom
for patch in dify-patches/*.patch; do
  git apply $patch
done

2. Separate customization layer

/custom/
  /i18n/fa-IR.json      # Your translations
  /components/          # Override components
  /themes/brand.css     # Branding

Mount these at build time or runtime.

3. Git subtree for upstream

git subtree add --prefix=upstream https://github.com/langgenius/dify main
# Your changes in /custom, /overrides
git subtree pull --prefix=upstream ... # Update upstream

4. Protected files via .gitattributes

custom/** merge=ours
i18n/fa-IR.json merge=ours

5. Build-time injection

FROM langgenius/dify:latest
COPY ./custom/i18n /app/web/i18n
COPY ./custom/brand /app/web/public

Recommendation:
Keep upstream untouched. Apply customizations as an overlay layer at build time. This makes upgrades a matter of rebuilding, not resolving conflicts.

We maintain customized AI platforms at Revolution AI — the overlay pattern saves hours on every upgrade.