Add Korean localization and CLAUDE.md documentation

- Localize UI labels and example prompts to Korean
- Add CLAUDE.md with architecture overview and development guidance
- Translate all Gradio interface elements (title, labels, placeholders, buttons)
- Translate error messages to Korean

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Z-Image-Turbo is a Gradio-based Hugging Face Space for image generation using the Z-Image diffusion transformer model. It provides a web interface for text-to-image generation with optional prompt enhancement via API.
+
+## Running the Application
+
+**Start the Gradio app:**
+```bash
+python app.py
+```
+
+The app will launch with MCP server support enabled and be accessible via the Gradio interface.
+
+## Environment Variables
+
+Required environment variables (set these before running):
+
+- `MODEL_PATH`: Path or HF model ID (default: "Tongyi-MAI/Z-Image-Turbo")
+- `HF_TOKEN`: Hugging Face token for model access
+- `DASHSCOPE_API_KEY`: Optional, for prompt enhancement feature (currently disabled in UI)
+- `ENABLE_COMPILE`: Enable torch.compile optimizations (default: "true")
+- `ENABLE_WARMUP`: Warmup model on startup (default: "true")
+- `ATTENTION_BACKEND`: Attention implementation (default: "flash_3")
+
+## Architecture
+
+### Core Components
+
+**app.py** - Main application file containing:
+- Model loading and initialization (`load_models`, `init_app`)
+- Image generation pipeline using ZImagePipeline from diffusers
+- Gradio UI with resolution presets and generation controls
+- Optional prompt enhancement via DashScope API (currently disabled in UI)
+- Zero GPU integration with AoTI (Ahead of Time Inductor) compilation
+
+**pe.py** - Contains `prompt_template` for the prompt expander, a Chinese language system prompt that guides LLMs to transform user prompts into detailed visual descriptions suitable for image generation models.
+
+### Key Functions
+
+**`generate(prompt, resolution, seed, steps, shift, enhance, random_seed, gallery_images, progress)`** (app.py:366)
+- Main generation function decorated with `@spaces.GPU`
+- Processes prompt, applies settings, generates image
+- Returns updated gallery, seed used
+- The `enhance` parameter is currently disabled in the UI but functional in code
+
+**`load_models(model_path, enable_compile, attention_backend)`** (app.py:100)
+- Loads VAE, text encoder, tokenizer, and transformer
+- Applies torch.compile optimizations if enabled
+- Configures attention backend (native/flash_3)
+
+**`warmup_model(pipe, resolutions)`** (app.py:205)
+- Pre-warms model for all resolution configurations
+- Reduces first-generation latency
+
+### Resolution System
+
+The app supports two resolution categories (1024 and 1280) with multiple aspect ratios:
+- 1:1, 9:7, 7:9, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 9:21
+- Resolutions are stored in `RES_CHOICES` dict and parsed via `get_resolution()`
+
+### Prompt Enhancement (Currently Disabled)
+
+The `PromptExpander` and `APIPromptExpander` classes provide optional prompt enhancement via DashScope API:
+- Backend: OpenAI-compatible API at dashscope.aliyuncs.com
+- Model: qwen3-max-preview
+- System prompt from `pe.prompt_template` guides detailed visual description generation
+- UI controls are commented out but underlying code is functional
+
+## Dependencies
+
+Install via:
+```bash
+pip install -r requirements.txt
+```
+
+Key dependencies:
+- gradio (UI framework)
+- torch, transformers, diffusers (ML models)
+- spaces (Hugging Face Spaces integration)
+- openai (for optional prompt enhancement)
+- Custom diffusers fork from GitHub with Z-Image support
+
+## Model Details
+
+- Architecture: Single-stream diffusion transformer (Z-Image)
+- Scheduler: FlowMatchEulerDiscreteScheduler with configurable shift parameter
+- Precision: bfloat16
+- Device: CUDA required
+- Attention: Configurable backend (native or flash_3)
+
+## Zero GPU Integration
+
+The app uses Hugging Face Spaces Zero GPU features:
+- `@spaces.GPU` decorator on generate function
+- AoTI (Ahead of Time Inductor) compilation for transformer blocks (app.py:458-459)
+- Pre-compiled blocks loaded from "zerogpu-aoti/Z-Image" with flash_attention_3 variant

app.py

@@ -68,24 +68,24 @@ for resolutions in RES_CHOICES.values():
     RESOLUTION_SET.extend(resolutions)
 
 EXAMPLE_PROMPTS = [
-    ["一位男士和他的贵宾犬穿着配套的服装参加狗狗秀，室内灯光，背景中有观众。"],
+    ["한 남성과 그의 푸들이 어울리는 의상을 입고 실내 조명 아래 관객들이 있는 배경에서 개 쇼에 참가하고 있는 모습."],
     [
-        "极具氛围感的暗调人像，一位优雅的中国美女在黑暗的房间里。一束强光通过遮光板，在她的脸上投射出一个清晰的闪电形状的光影，正好照亮一只眼睛。高对比度，明暗交界清晰，神秘感，莱卡相机色调。"
+        "분위기 있는 어두운 톤의 인물 사진, 우아한 중국 여성이 어두운 방에 있다. 강한 빛이 셔터를 통과해 그녀의 얼굗에 번개 모양의 선명한 빛과 그림자를 투사하며 한쪽 눈만을 정확히 비춘다. 높은 대비, 명암 경계가 선명하며, 신비로운 느낌, 라이카 카메라 색조."
     ],
     [
-        "一张中景手机自拍照片拍摄了一位留着长黑发的年轻东亚女子在灯光明亮的电梯内对着镜子自拍。她穿着一件带有白色花朵图案的黑色露肩短上衣和深色牛仔裤。她的头微微倾斜，嘴唇嘟起做亲吻状，非常可爱俏皮。她右手拿着一部深灰色智能手机，遮住了部分脸，后置摄像头镜头对着镜子"
+        "밝게 조명된 엘리베이터 안에서 긴 검은 머리를 한 젊은 동아시아 여성이 거울을 향해 셀카를 찍는 중간 거리 스마트폰 셀카 사진. 그녀는 흰색 꽃무늬가 있는 검은색 오프숄더 크롭탑과 어두운 청바지를 입고 있다. 머리를 약간 기울이고 입술을 뾰족하게 내밀어 키스하는 듯한 포즈로 매우 귀엽고 장난스러운 모습이다. 오른손에 짙은 회색 스마트폰을 들고 얼굴 일부를 가리고 있으며, 후면 카메라 렌즈가 거울을 향하고 있다."
     ],
     [
-        "Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. Neon lightning-bolt lamp (⚡️), bright yellow glow, above extended left palm. Soft-lit outdoor night background, silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights."
+        "빨간 한푸를 입은 젊은 중국 여성, 정교한 자수. 완벽한 메이크업, 붉은 꽃무늬 이마 장식. 정교한 높은 쪽진 머리, 금빛 봉황 머리 장식, 붉은 꽃, 구슬. 여인과 나무, 새가 그려진 둥근 접이식 부채를 들고 있다. 네온 번개 모양 램프 (⚡️), 밝은 노란색 빛, 펼친 왼쪽 손바닥 위에. 부드럽게 조명된 야외 밤 배경, 실루엣의 다층 탑(서안 대안탑), 흐릿한 컬러 먼 불빛들."
     ],
     [
-        '''A vertical digital illustration depicting a serene and majestic Chinese landscape, rendered in a style reminiscent of traditional Shanshui painting but with a modern, clean aesthetic. The scene is dominated by towering, steep cliffs in various shades of blue and teal, which frame a central valley. In the distance, layers of mountains fade into a light blue and white mist, creating a strong sense of atmospheric perspective and depth. A calm, turquoise river flows through the center of the composition, with a small, traditional Chinese boat, possibly a sampan, navigating its waters. The boat has a bright yellow canopy and a red hull, and it leaves a gentle wake behind it. It carries several indistinct figures of people. Sparse vegetation, including green trees and some bare-branched trees, clings to the rocky ledges and peaks. The overall lighting is soft and diffused, casting a tranquil glow over the entire scene. Centered in the image is overlaid text. At the top of the text block is a small, red, circular seal-like logo containing stylized characters. Below it, in a smaller, black, sans-serif font, are the words 'Zao-Xiang * East Beauty & West Fashion * Z-Image'. Directly beneath this, in a larger, elegant black serif font, is the word 'SHOW & SHARE CREATIVITY WITH THE WORLD'. Among them, there are "SHOW & SHARE", "CREATIVITY", and "WITH THE WORLD"'''
+        '''고요하고 장엄한 중국 풍경을 묘사한 세로 형식의 디지털 일러스트레이션으로, 전통적인 산수화 스타일을 현대적이고 깔끔한 미학으로 재해석했다. 장면은 중앙 계곡을 둘러싼 다양한 파란색과 청록색 음영의 우뚝 솟은 가파른 절벽이 지배한다. 멀리 산들이 층층이 연한 파란색과 흰색 안개 속으로 사라지며 강한 대기 원근감과 깊이를 만들어낸다. 고요한 청록색 강이 구성의 중앙을 가로질러 흐르며, 작은 전통 중국 배, 아마도 삼판이 물 위를 항해하고 있다. 배는 밝은 노란색 천막과 붉은 선체를 가지고 있으며 뒤에 부드러운 물결을 남긴다. 여러 명의 희미한 인물들을 태우고 있다. 녹색 나무와 일부 맨가지 나무를 포함한 드문드문한 식생이 바위 선반과 봉우리에 붙어 있다. 전체 조명은 부드럽고 확산되어 전체 장면에 평온한 빛을 드리운다. 이미지 중앙에 텍스트가 겹쳐져 있다. 텍스트 블록 상단에는 양식화된 문자가 포함된 작고 빨간색의 원형 도장 같은 로고가 있다. 그 아래 작은 검은색 산세리프 글꼴로 'Zao-Xiang * East Beauty & West Fashion * Z-Image'라는 단어가 있다. 그 바로 아래 더 큰 우아한 검은색 세리프 글꼴로 'SHOW & SHARE CREATIVITY WITH THE WORLD'라는 단어가 있다. 그 중에는 "SHOW & SHARE", "CREATIVITY", "WITH THE WORLD"가 있다.'''
     ],
     [
-        """一张虚构的英语电影《回忆之味》（The Taste of Memory）的电影海报。场景设置在一个质朴的19世纪风格厨房里。画面中央，一位红棕色头发、留着小胡子的中年男子（演员阿瑟·彭哈利根饰）站在一张木桌后，他身穿白色衬衫、黑色马甲和米色围裙，正看着一位女士，手中拿着一大块生红肉，下方是一个木制切菜板。在他的右边，一位梳着高髻的黑发女子（演员埃莉诺·万斯饰）倚靠在桌子上，温柔地对他微笑。她穿着浅色衬衫和一条上白下蓝的长裙。桌上除了放有切碎的葱和卷心菜丝的切菜板外，还有一个白色陶瓷盘、新鲜香草，左侧一个木箱上放着一串深色葡萄。背景是一面粗糙的灰白色抹灰墙，墙上挂着一幅风景画。最右边的一个台面上放着一盏复古油灯。海报上有大量的文字信息。左上角是白色的无衬线字体"ARTISAN FILMS PRESENTS"，其下方是"ELEANOR VANCE"和"ACADEMY AWARD® WINNER"。右上角写着"ARTHUR PENHALIGON"和"GOLDEN GLOBE® AWARD WINNER"。顶部中央是圣丹斯电影节的桂冠标志，下方写着"SUNDANCE FILM FESTIVAL GRAND JURY PRIZE 2024"。主标题"THE TASTE OF MEMORY"以白色的大号衬线字体醒目地显示在下半部分。标题下方注明了"A FILM BY Tongyi Interaction Lab"。底部区域用白色小字列出了完整的演职员名单，包括"SCREENPLAY BY ANNA REID"、"CULINARY DIRECTION BY JAMES CARTER"以及Artisan Films、Riverstone Pictures和Heritage Media等众多出品公司标志。整体风格是写实主义，采用温暖柔和的灯光方案，营造出一种亲密的氛围。色调以棕色、米色和柔和的绿色等大地色系为主。两位演员的身体都在腰部被截断。"""
+        """가상의 영화 《회상의 맛》(The Taste of Memory)의 영화 포스터. 장면은 소박한 19세기 스타일 주방에 설정되어 있다. 화면 중앙에 적갈색 머리와 작은 콧수염을 가진 중년 남성(배우 아서 펜할리건 연기)이 나무 테이블 뒤에 서 있으며, 흰색 셔츠, 검은색 조끼, 베이지색 앞치마를 입고 있고 한 여성을 바라보며 손에 큰 덩어리의 생고기를 들고 있으며 아래에는 나무 도마가 있다. 그의 오른쪽에는 높은 쪽진 머리를 한 검은 머리 여성(배우 엘리너 밴스 연기)이 테이블에 기대어 그에게 부드럽게 미소짓고 있다. 그녀는 연한 색 셔츠와 상단은 흰색, 하단은 파란색인 긴 치마를 입고 있다. 테이블 위에는 다진 파와 양배추 채가 있는 도마 외에도 흰색 도자기 접시, 신선한 허브가 있고, 왼쪽 나무 상자 위에는 짙은 색 포도 한 송이가 놓여 있다. 배경은 거칠게 회백색으로 미장된 벽이며 풍경화 한 점이 걸려 있다. 가장 오른쪽 작업대 위에는 복고풍 오일 램프가 놓여 있다. 포스터에는 많은 텍스트 정보가 있다. 왼쪽 상단에는 흰색 산세리프 글꼴로 "ARTISAN FILMS PRESENTS"가 있고 그 아래에 "ELEANOR VANCE"와 "ACADEMY AWARD® WINNER"가 있다. 오른쪽 상단에는 "ARTHUR PENHALIGON"과 "GOLDEN GLOBE® AWARD WINNER"가 쓰여 있다. 상단 중앙에는 선댄스 영화제 월계관 로고가 있고 아래에 "SUNDANCE FILM FESTIVAL GRAND JURY PRIZE 2024"가 쓰여 있다. 주요 제목 "THE TASTE OF MEMORY"는 흰색의 큰 세리프 글꼴로 하단에 눈에 띄게 표시되어 있다. 제목 아래에는 "A FILM BY Tongyi Interaction Lab"이 명시되어 있다. 하단 영역에는 흰색 작은 글씨로 "SCREENPLAY BY ANNA REID", "CULINARY DIRECTION BY JAMES CARTER" 및 Artisan Films, Riverstone Pictures, Heritage Media 등 수많은 제작사 로고를 포함한 전체 출연진 및 제작진 명단이 나열되어 있다. 전체적인 스타일은 사실주의로 따뜻하고 부드러운 조명 방식을 채택하여 친밀한 분위기를 조성한다. 색조는 갈색, 베이지, 부드러운 녹색 등 대지색 톤이 주를 이룬다. 두 배우의 몸은 모두 허리에서 잘려 있다."""
     ],
     [
-        """一张方形构图的特写照片，主体是一片巨大的、鲜绿色的植物叶片，并叠加了文字，使其具有海报或杂志封面的外观。主要拍摄对象是一片厚实、有蜡质感的叶子，从左下角到右上角呈对角线弯曲穿过画面。其表面反光性很强，捕捉到一个明亮的直射光源，形成了一道突出的高光，亮面下显露出平行的精细叶脉。背景由其他深绿色的叶子组成，这些叶子轻微失焦，营造出浅景深效果，突出了前景的主叶片。整体风格是写实摄影，明亮的叶片与黑暗的阴影背景之间形成高对比度。图像上有多处渲染文字。左上角是白色的衬线字体文字"PIXEL-PEEPERS GUILD Presents"。右上角同样是白色衬线字体的文字"[Instant Noodle] 泡面调料包"。左侧垂直排列着标题"Render Distance: Max"，为白色衬线字体。左下角是五个硕大的白色宋体汉字"显卡在...燃烧"。右下角是较小的白色衬线字体文字"Leica Glow™ Unobtanium X-1"，其正上方是用白色宋体字书写的名字"蔡几"。识别出的核心实体包括品牌像素偷窥者协会、其产品线泡面调料包、相机型号买不到™ X-1以及摄影师名字造相。"""
+        """정사각형 구도의 클로즈업 사진으로, 거대하고 선명한 녹색 식물 잎이 주제이며 텍스트가 겹쳐져 포스터나 잡지 표지 같은 외관을 갖추고 있다. 주요 피사체는 왼쪽 하단에서 오른쪽 상단으로 대각선으로 구부러져 프레임을 가로지르는 두껍고 왁스 같은 질감의 잎이다. 표면이 매우 반사적이어서 밝은 직사광원을 포착하여 두드러진 하이라이트를 형성하고 밝은 면 아래 평행한 미세 잎맥이 드러난다. 배경은 다른 짙은 녹색 잎들로 구성되어 있으며 약간 초점이 흐려져 얕은 피사계 심도 효과를 만들어 전경의 주요 잎을 강조한다. 전체적인 스타일은 사실적인 사진으로 밝은 잎과 어두운 그림자 배경 사이에 높은 대비를 형성한다. 이미지에는 여러 렌더링된 텍스트가 있다. 왼쪽 상단에는 흰색 세리프 글꼴로 "PIXEL-PEEPERS GUILD Presents"라는 텍스트가 있다. 오른쪽 상단에도 흰색 세리프 글꼴로 "[Instant Noodle] 泡面调料包"라는 텍스트가 있다. 왼쪽에는 수직으로 배열된 제목 "Render Distance: Max"가 흰색 세리프 글꼴로 되어 있다. 왼쪽 하단에는 다섯 개의 거대한 흰색 송체 한자 "显卡在...燃烧"가 있다. 오른쪽 하단에는 작은 흰색 세리프 글꼴로 "Leica Glow™ Unobtanium X-1"이 있고, 그 바로 위에는 흰색 송체로 쓰인 이름 "蔡几"가 있다. 식별된 핵심 개체에는 브랜드 픽셀 피퍼스 길드, 제품 라인 인스턴트 누들 조미료 패키지, 카메라 모델 Unobtanium™ X-1 및 사진가 이름 Zao-Xiang이 포함된다."""
     ],
 ]
 
@@ -348,19 +348,19 @@ def init_app():
 
 def prompt_enhance(prompt, enable_enhance):
     if not enable_enhance or not prompt_expander:
-        return prompt, "Enhancement disabled or not available."
+        return prompt, "프롬프트 향상이 비활성화되었거나 사용할 수 없습니다."
 
     if not prompt.strip():
-        return "", "Please enter a prompt."
+        return "", "프롬프트를 입력해주세요."
 
     try:
         result = prompt_expander(prompt)
         if result.status:
             return result.prompt, result.message
         else:
-            return prompt, f"Enhancement failed: {result.message}"
+            return prompt, f"향상 실패: {result.message}"
     except Exception as e:
-        return prompt, f"Error: {str(e)}"
+        return prompt, f"오류: {str(e)}"
 
 
 @spaces.GPU
@@ -416,7 +416,7 @@ def generate(
             - seed_int: Integer representation of the seed used for generation
     """
     if pipe is None:
-        raise gr.Error("Model not loaded.")
+        raise gr.Error("모델이 로드되지 않았습니다.")
 
     final_prompt = prompt
 
@@ -458,53 +458,53 @@ init_app()
 pipe.transformer.layers._repeated_blocks = ["ZImageTransformerBlock"]
 spaces.aoti_blocks_load(pipe.transformer.layers, "zerogpu-aoti/Z-Image", variant="fa3")
 
-with gr.Blocks(title="Z-Image Demo") as demo:
+with gr.Blocks(title="Z-Image 데모") as demo:
     gr.Markdown(
         """<div align="center">
-        
-# Z-Image Generation Demo
+
+# Z-Image 이미지 생성 데모
 
 [![GitHub](https://img.shields.io/badge/GitHub-Z--Image-181717?logo=github&logoColor=white)](https://github.com/Tongyi-MAI/Z-Image)
 
-*An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer*
+*단일 스트림 디퓨전 트랜스포머를 사용한 효율적인 이미지 생성 기반 모델*
 
 </div>"""
     )
 
     with gr.Row():
         with gr.Column(scale=1):
-            prompt_input = gr.Textbox(label="Prompt", lines=3, placeholder="Enter your prompt here...")
+            prompt_input = gr.Textbox(label="프롬프트", lines=3, placeholder="프롬프트를 입력하세요...")
             # PE components (Temporarily disabled)
             # with gr.Row():
-            #     enable_enhance = gr.Checkbox(label="Enhance Prompt (DashScope)", value=False)
-            #     enhance_btn = gr.Button("Enhance Only")
+            #     enable_enhance = gr.Checkbox(label="프롬프트 향상 (DashScope)", value=False)
+            #     enhance_btn = gr.Button("향상만 실행")
 
             with gr.Row():
                 choices = [int(k) for k in RES_CHOICES.keys()]
-                res_cat = gr.Dropdown(value=1024, choices=choices, label="Resolution Category")
+                res_cat = gr.Dropdown(value=1024, choices=choices, label="해상도 카테고리")
 
                 initial_res_choices = RES_CHOICES["1024"]
-                resolution = gr.Dropdown(value=initial_res_choices[0], choices=RESOLUTION_SET, label="Width x Height (Ratio)")
+                resolution = gr.Dropdown(value=initial_res_choices[0], choices=RESOLUTION_SET, label="너비 x 높이 (비율)")
 
             with gr.Row():
-                seed = gr.Number(label="Seed", value=42, precision=0)
-                random_seed = gr.Checkbox(label="Random Seed", value=True)
+                seed = gr.Number(label="시드", value=42, precision=0)
+                random_seed = gr.Checkbox(label="랜덤 시드", value=True)
 
             with gr.Row():
-                steps = gr.Slider(label="Steps", minimum=1, maximum=100, value=8, step=1, interactive=False)
-                shift = gr.Slider(label="Time Shift", minimum=1.0, maximum=10.0, value=3.0, step=0.1)
+                steps = gr.Slider(label="스텝 수", minimum=1, maximum=100, value=8, step=1, interactive=False)
+                shift = gr.Slider(label="시간 이동", minimum=1.0, maximum=10.0, value=3.0, step=0.1)
 
-            generate_btn = gr.Button("Generate", variant="primary")
+            generate_btn = gr.Button("생성", variant="primary")
 
             # Example prompts
-            gr.Markdown("### 📝 Example Prompts")
+            gr.Markdown("### 📝 예제 프롬프트")
             gr.Examples(examples=EXAMPLE_PROMPTS, inputs=prompt_input, label=None)
 
         with gr.Column(scale=1):
             output_gallery = gr.Gallery(
-                label="Generated Images", columns=2, rows=2, height=600, object_fit="contain", format="png", interactive=False
+                label="생성된 이미지", columns=2, rows=2, height=600, object_fit="contain", format="png", interactive=False
             )
-            used_seed = gr.Textbox(label="Seed Used", interactive=False)
+            used_seed = gr.Textbox(label="사용된 시드", interactive=False)
 
     def update_res_choices(_res_cat):
         if str(_res_cat) in RES_CHOICES: