@intlayer/cli 7.1.3 → 7.1.5

package/dist/assets/translation-alignment/QUICK_START.md

@@ -1,494 +0,0 @@
-# Quick Start Guide
-
-Get started with the block-aware translation alignment system in 5 minutes.
-
-## Installation
-
-The system is already integrated into your CLI package. No additional dependencies needed.
-
-## Basic Usage
-
-### 1. Simple Translation Review
-
-```typescript
-import { reviewFileBlockAware } from './reviewDocBlockAware';
-import { Locales } from '@intlayer/types';
-
-await reviewFileBlockAware(
-  'docs/en/getting-started.md',   // Source file
-  'docs/fr/getting-started.md',   // Target file
-  Locales.FRENCH,                 // Target locale
-  Locales.ENGLISH                 // Source locale
-);
-```
-
-### 2. With Git Integration
-
-```typescript
-import { listGitLines } from '@intlayer/chokidar';
-
-const changedLines = await listGitLines(
-  'docs/en/getting-started.md',
-  { sinceDays: 7 }  // Changes in last 7 days
-);
-
-await reviewFileBlockAware(
-  'docs/en/getting-started.md',
-  'docs/fr/getting-started.md',
-  Locales.FRENCH,
-  Locales.ENGLISH,
-  aiOptions,
-  configOptions,
-  undefined,
-  changedLines  // Only review changed blocks!
-);
-```
-
-### 3. With Custom AI Instructions
-
-```typescript
-const customInstructions = `
-- Use formal French (vous, not tu)
-- Preserve technical terminology in English
-- Maintain consistent tone
-`;
-
-await reviewFileBlockAware(
-  'docs/en/api.md',
-  'docs/fr/api.md',
-  Locales.FRENCH,
-  Locales.ENGLISH,
-  aiOptions,
-  configOptions,
-  customInstructions
-);
-```
-
-## Using the Pipeline Directly
-
-For more control, use the pipeline API:
-
-```typescript
-import { buildAlignmentPlan, mergeReviewedSegments } from './translation-alignment/pipeline';
-
-// 1. Build alignment plan
-const { englishBlocks, frenchBlocks, plan, segmentsToReview } = buildAlignmentPlan({
-  englishText: await readFile('docs/en/guide.md', 'utf-8'),
-  frenchText: await readFile('docs/fr/guide.md', 'utf-8'),
-  changedLines: [10, 15, 20],
-  similarityOptions: {
-    minimumMatchForReuse: 0.92,
-  },
-});
-
-// 2. Log plan details
-console.log(`Blocks to reuse: ${plan.actions.filter(a => a.kind === 'reuse').length}`);
-console.log(`Blocks to review: ${segmentsToReview.length}`);
-
-// 3. Translate segments (your AI logic here)
-const reviewedMap = new Map();
-for (const segment of segmentsToReview) {
-  const translation = await yourTranslationFunction(segment.englishBlock.content);
-  reviewedMap.set(segment.actionIndex, translation);
-}
-
-// 4. Merge and output
-const finalOutput = mergeReviewedSegments(plan, frenchBlocks, reviewedMap);
-await writeFile('docs/fr/guide.md', finalOutput);
-```
-
-## Common Scenarios
-
-### Scenario 1: New Document (No Translation Exists)
-
-```typescript
-// French file doesn't exist yet
-await reviewFileBlockAware(
-  'docs/en/new-feature.md',
-  'docs/fr/new-feature.md',  // Will be created
-  Locales.FRENCH,
-  Locales.ENGLISH
-);
-
-// Result: All blocks translated from scratch
-```
-
-### Scenario 2: Minor Edit (2 paragraphs changed)
-
-```typescript
-// Git shows lines 45-60 changed
-const changedLines = [45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60];
-
-await reviewFileBlockAware(
-  'docs/en/guide.md',
-  'docs/fr/guide.md',
-  Locales.FRENCH,
-  Locales.ENGLISH,
-  aiOptions,
-  configOptions,
-  undefined,
-  changedLines
-);
-
-// Result: Only 2 blocks sent to AI, 98% reused
-```
-
-### Scenario 3: Reordered Sections
-
-```markdown
-<!-- Before -->
-## Installation
-## Configuration
-## Usage
-
-<!-- After -->
-## Installation
-## Usage
-## Configuration
-```
-
-```typescript
-await reviewFileBlockAware(
-  'docs/en/guide.md',
-  'docs/fr/guide.md',
-  Locales.FRENCH,
-  Locales.ENGLISH
-);
-
-// Result: Sections automatically reordered, 0 AI calls needed
-```
-
-### Scenario 4: Added Section
-
-```markdown
-<!-- Before -->
-## Installation
-## Usage
-
-<!-- After -->
-## Installation
-## Configuration  ← NEW
-## Usage
-```
-
-```typescript
-await reviewFileBlockAware(
-  'docs/en/guide.md',
-  'docs/fr/guide.md',
-  Locales.FRENCH,
-  Locales.ENGLISH
-);
-
-// Result: 
-// - Installation: reused
-// - Configuration: translated (1 AI call)
-// - Usage: reused
-```
-
-### Scenario 5: Deleted Section
-
-```markdown
-<!-- Before -->
-## Installation
-## Deprecated  ← DELETE
-## Usage
-
-<!-- After -->
-## Installation
-## Usage
-```
-
-```typescript
-await reviewFileBlockAware(
-  'docs/en/guide.md',
-  'docs/fr/guide.md',
-  Locales.FRENCH,
-  Locales.ENGLISH
-);
-
-// Result: 
-// - Installation: reused
-// - Deprecated: deleted from output
-// - Usage: reused
-```
-
-## Batch Processing
-
-Process multiple files:
-
-```typescript
-import fg from 'fast-glob';
-
-const englishFiles = await fg('docs/en/**/*.md');
-
-for (const englishFile of englishFiles) {
-  const frenchFile = englishFile.replace('/en/', '/fr/');
-  
-  await reviewFileBlockAware(
-    englishFile,
-    frenchFile,
-    Locales.FRENCH,
-    Locales.ENGLISH,
-    aiOptions,
-    configOptions
-  );
-}
-```
-
-## Monitoring & Debugging
-
-### Enable Verbose Logging
-
-```typescript
-import { getConfiguration, getAppLogger } from '@intlayer/config';
-
-const configuration = getConfiguration();
-const logger = getAppLogger(configuration);
-
-// Logger will output:
-// - Block segmentation results
-// - Alignment statistics
-// - Action plan details
-// - Token usage per block
-// - Efficiency metrics
-```
-
-### Inspect Alignment Plan
-
-```typescript
-const { plan, segmentsToReview } = buildAlignmentPlan({
-  englishText,
-  frenchText,
-  changedLines,
-});
-
-// Analyze plan
-plan.actions.forEach((action, index) => {
-  console.log(`Action ${index}: ${action.kind}`);
-  if (action.kind === 'reuse') {
-    console.log(`  English block ${action.englishIndex} → French block ${action.frenchIndex}`);
-  } else if (action.kind === 'review') {
-    console.log(`  Reviewing English block ${action.englishIndex}`);
-  }
-});
-```
-
-### Debug Block Segmentation
-
-```typescript
-import { segmentDocument } from './translation-alignment/segmentDocument';
-
-const blocks = segmentDocument(englishText);
-
-blocks.forEach((block, index) => {
-  console.log(`Block ${index}:`);
-  console.log(`  Type: ${block.type}`);
-  console.log(`  Lines: ${block.lineStart}-${block.lineEnd}`);
-  console.log(`  Content preview: ${block.content.slice(0, 50)}...`);
-});
-```
-
-### Analyze Similarity Scores
-
-```typescript
-import { computeJaccardSimilarity } from './translation-alignment/computeSimilarity';
-
-const similarity = computeJaccardSimilarity(
-  "Hello [World](https://example.com)",
-  "Bonjour [Monde](https://example.com)",
-  3
-);
-
-console.log(`Similarity: ${(similarity * 100).toFixed(1)}%`);
-// Output: Similarity: 75.3%
-```
-
-## Configuration Tuning
-
-### Adjust Similarity Thresholds
-
-```typescript
-const { plan } = buildAlignmentPlan({
-  englishText,
-  frenchText,
-  changedLines,
-  similarityOptions: {
-    // Higher = more conservative (more blocks reviewed)
-    minimumMatchForReuse: 0.95,
-    
-    // For future near-duplicate detection
-    minimumMatchForNearDuplicate: 0.85,
-  },
-});
-```
-
-### Finding Optimal Thresholds
-
-Run experiments:
-
-```typescript
-const thresholds = [0.85, 0.87, 0.90, 0.92, 0.95, 0.97];
-const results = [];
-
-for (const threshold of thresholds) {
-  const { plan } = buildAlignmentPlan({
-    englishText,
-    frenchText,
-    changedLines,
-    similarityOptions: { minimumMatchForReuse: threshold },
-  });
-  
-  const reusedCount = plan.actions.filter(a => a.kind === 'reuse').length;
-  const reviewCount = plan.actions.filter(a => a.kind === 'review').length;
-  
-  results.push({
-    threshold,
-    reused: reusedCount,
-    reviewed: reviewCount,
-    efficiency: (reusedCount / plan.actions.length * 100).toFixed(1) + '%',
-  });
-}
-
-console.table(results);
-```
-
-Example output:
-
-```
-┌─────────┬───────────┬────────┬──────────┬────────────┐
-│ (index) │ threshold │ reused │ reviewed │ efficiency │
-├─────────┼───────────┼────────┼──────────┼────────────┤
-│    0    │   0.85    │   92   │    8     │  '92.0%'   │
-│    1    │   0.87    │   90   │    10    │  '90.0%'   │
-│    2    │   0.90    │   88   │    12    │  '88.0%'   │
-│    3    │   0.92    │   85   │    15    │  '85.0%'   │
-│    4    │   0.95    │   80   │    20    │  '80.0%'   │
-│    5    │   0.97    │   72   │    28    │  '72.0%'   │
-└─────────┴───────────┴────────┴──────────┴────────────┘
-```
-
-Choose based on your priorities:
-- **High accuracy**: Use 0.95+ (more AI reviews)
-- **High efficiency**: Use 0.85-0.90 (fewer AI reviews)
-- **Balanced**: Use 0.90-0.92 (default)
-
-## Testing
-
-### Unit Test Example
-
-```typescript
-import { segmentDocument } from './translation-alignment/segmentDocument';
-
-describe('Block Segmentation', () => {
-  it('should segment markdown correctly', () => {
-    const input = '# Title\n\nParagraph 1\n\n## Subtitle\n\nParagraph 2\n';
-    const blocks = segmentDocument(input);
-    
-    expect(blocks).toHaveLength(4);
-    expect(blocks[0].type).toBe('heading');
-    expect(blocks[0].content).toBe('# Title\n');
-    expect(blocks[1].type).toBe('paragraph');
-    expect(blocks[2].type).toBe('heading');
-    expect(blocks[3].type).toBe('paragraph');
-  });
-});
-```
-
-### Integration Test Example
-
-```typescript
-import { buildAlignmentPlan } from './translation-alignment/pipeline';
-
-describe('Reordering Detection', () => {
-  it('should detect reordered paragraphs', () => {
-    const englishV1 = 'Para A\n\nPara B\n\nPara C\n';
-    const englishV2 = 'Para B\n\nPara A\n\nPara C\n';
-    const frenchV1 = 'Para A (fr)\n\nPara B (fr)\n\nPara C (fr)\n';
-    
-    const { plan, segmentsToReview } = buildAlignmentPlan({
-      englishText: englishV2,
-      frenchText: frenchV1,
-      changedLines: undefined,
-    });
-    
-    // All blocks should be reused (just reordered)
-    expect(segmentsToReview).toHaveLength(0);
-    const reusedCount = plan.actions.filter(a => a.kind === 'reuse').length;
-    expect(reusedCount).toBe(3);
-  });
-});
-```
-
-## Troubleshooting
-
-### Problem: Too Many Blocks Marked for Review
-
-```typescript
-// Check if threshold is too high
-const { plan } = buildAlignmentPlan({
-  englishText,
-  frenchText,
-  changedLines,
-  similarityOptions: { minimumMatchForReuse: 0.85 }, // Lower threshold
-});
-```
-
-### Problem: Blocks Not Aligning Correctly
-
-```typescript
-// Debug anchor text extraction
-import { normalizeBlock } from './translation-alignment/normalizeBlock';
-import { segmentDocument } from './translation-alignment/segmentDocument';
-
-const blocks = segmentDocument(englishText);
-const normalized = blocks.map(normalizeBlock);
-
-normalized.forEach((block, index) => {
-  console.log(`Block ${index}:`);
-  console.log(`  Semantic: ${block.semanticText.slice(0, 50)}`);
-  console.log(`  Anchor: ${block.anchorText}`);
-});
-```
-
-### Problem: Output Has Extra Blank Lines
-
-```typescript
-// Check block content preservation
-const { englishBlocks } = buildAlignmentPlan({
-  englishText,
-  frenchText,
-  changedLines,
-});
-
-englishBlocks.forEach((block, index) => {
-  const hasTrailingNewline = block.content.endsWith('\n');
-  console.log(`Block ${index}: trailing newline = ${hasTrailingNewline}`);
-});
-```
-
-## Performance Tips
-
-1. **Always use Git integration** when available for maximum efficiency
-2. **Batch process during off-peak hours** to reduce API rate limit issues
-3. **Cache fingerprints** for documents that don't change often
-4. **Use parallel processing** for multiple locales (built into `reviewDoc`)
-5. **Monitor token usage** and adjust thresholds if costs are too high
-
-## Next Steps
-
-- Read [README.md](./README.md) for detailed architecture
-- Review [IMPROVEMENTS.md](./IMPROVEMENTS.md) for comparison with old system
-- Follow [INTEGRATION_EXAMPLE.md](./INTEGRATION_EXAMPLE.md) for production deployment
-- Check [TESTING.md](./TESTING.md) for comprehensive test examples
-
-## Support
-
-For issues or questions:
-1. Check logs for alignment details
-2. Verify input markdown is valid
-3. Test with simplified example
-4. Review similarity scores
-5. Open an issue with sample files
-
-Happy translating! 🌍
-