From b562211aa56da1131aeaf70f212700ae0e88523d Mon Sep 17 00:00:00 2001 From: Yusuf Sabbag Date: Sat, 5 Jun 2021 15:23:35 +0300 Subject: [PATCH 1/5] Added Arabic translation folder --- translations/ar-AR/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 translations/ar-AR/README.md diff --git a/translations/ar-AR/README.md b/translations/ar-AR/README.md new file mode 100644 index 0000000..e69de29 From d2ff00309dae7e6173724a0ea85a13aba3c1025c Mon Sep 17 00:00:00 2001 From: Yusuf Sabbag Date: Sat, 5 Jun 2021 20:53:49 +0300 Subject: [PATCH 2/5] Added Arabic into the translations list --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f9588fa..d861562 100644 --- a/README.md +++ b/README.md @@ -339,7 +339,7 @@ An example of various conventions. ## Translations - +* * [العربية/Arabic](https://github.com/Yuniac/idiomatic-css/tree/master/translations/ar-AR) * [Bahasa Indonesia](https://github.com/necolas/idiomatic-css/tree/master/translations/id-ID) * [Bulgarian](https://github.com/vestimir/idiomatic-css) * [Česky](https://github.com/necolas/idiomatic-css/tree/master/translations/cs-CZ) From f8b97a7ab0c11e3deb7f0369194b4223daa3fa5e Mon Sep 17 00:00:00 2001 From: Yusuf Sabbag Date: Sat, 5 Jun 2021 20:54:14 +0300 Subject: [PATCH 3/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d861562..63298b1 100644 --- a/README.md +++ b/README.md @@ -339,7 +339,7 @@ An example of various conventions. ## Translations -* * [العربية/Arabic](https://github.com/Yuniac/idiomatic-css/tree/master/translations/ar-AR) +* [العربية/Arabic](https://github.com/Yuniac/idiomatic-css/tree/master/translations/ar-AR) * [Bahasa Indonesia](https://github.com/necolas/idiomatic-css/tree/master/translations/id-ID) * [Bulgarian](https://github.com/vestimir/idiomatic-css) * [Česky](https://github.com/necolas/idiomatic-css/tree/master/translations/cs-CZ) From 3087cb96c7212230955713056cc1d8d63b6e63f2 Mon Sep 17 00:00:00 2001 From: Yusuf Sabbag Date: Sat, 5 Jun 2021 20:55:37 +0300 Subject: [PATCH 4/5] Added Arabic translation --- translations/ar-AR/README.md | 345 +++++++++++++++++++++++++++++++++++ 1 file changed, 345 insertions(+) diff --git a/translations/ar-AR/README.md b/translations/ar-AR/README.md index e69de29..4497595 100644 --- a/translations/ar-AR/README.md +++ b/translations/ar-AR/README.md @@ -0,0 +1,345 @@ +
+ +# مبادئ كتابة CSS متناسق و إصطلاحي +

المستند التالي يحدد منهج كتابة منطقي لتطوير و كتابة كود ال"CSS". +هذا الدليل و كل محتواه يدعم و بشدة أنما‎ط حالية، شائعة و منطقية. يجب أن يتم أحتوا‎ئ هذه الأنماط و أستخدامها حسب حاجتك في كود ال"CSS" خاصتك.

+

هذا الدليل هو دليل نشط و حي و أفكار جديدة مرحب بها دائماً. رجا‎‎ءاً قُم بالمشاركة. +

+

+طاولة المحتوى +

+ + +1. [المبادئ العامة](#general-principles) +1. [المسافات البيضاء](#whitespace) +1. [التعليقات](#comments) +1. [الصيغة](#format) +1. [أمثلة عملية](#example) + +[شكر و تقدير](#acknowledgements) + +[الترخيص](#license) + + + +## 1. المبادئ العامة + +> "جزء من كونك عامل فاعل في أي مشروع ناجح هو إدراكك بأن كتابة كود من أجلك وحدك هو فكرة سيئة. لنفترض ان هناك ألاف من الناس يستخدمون الكود خاصتك، لذا يجب أن تكتب كودك بأوضح طريقة ممكنة و ليس بالطريقة التي تناسبك أنت شخصياً أو الطريقة التي لو كانت ذكية بالتلاعب بالكود و لكن غامضة و على الأ‎غلب غير مفهومة لأي شخص قد يقرأ كودك." Idan Gazit + +* لا تحاول التحايل على الكود أو تحسينه بطرق ملتوية في كل مكان، فضّل جعل الكود سهل القراءة و سهل الفهم +* كل الكود في أي مجموعة من الأكواد يجب أن يبدوا و كأنما شخص واحد كتبه حتى و لو كان في الواقع عدد كبير من الأشخاص كتبه. +* إلتزم بالقواعد المتعارف عليها. +* اذا كان لديك شك و حيرة حول أستخدام أي طريقة تنسيق، عندها أستعمل أكثر الطرق شيوعاً. + + + +## 2. المسافات البيضاء +

نُسق/تنسيق واحد فقط مسموح به في كل ‎جميع الأكواد خاصتك. +كُن ملتزم و ثابت بطريقة أستخدام مسافات بيضاء واحدة. أستخدم المسافات البيضاء من أجل تسهيل القراءة.

+ +* _أبداً_ لا تخلط أو تستخدم زر المسافة و زر التاب معاً من أجل التنسيق، ‎أستخدم واحداً فقط. +* أختر بين المسافات الصغيرة (زر المسافة Space"‎‎") أو المسافات الكبيرة (زر التاب "Tab"). أختر واحداً منهما و ألتزم به. (الأفضلية لأستخدام المسافات من نوع زر المسافة "Space"). +* إذا أخترت نوع المسافات من نوع زر المسافة "‎‎‎‎"Space فأختر عدد المسافات المُدخلة كل مرة ٢، ٤، إلخ. (الأفضلية ل ٤ مسافات). + +إرشاد: إضبط المحرر النصي خاصتك على "إظهار الحروف/الرموز المخفية" أو إضبط محررك على حذف المسافات البيضاء عند نهاية كل سطر. + +إرشاد: أستخدم ملف ["EditorConfig"](http://editorconfig.org/) (‎أو ما شابهه) لمساعدتك على الأحتفاظ بتنيسق مسافات بيضاء واحد متفق عليه حسب قواعد الكود خاصتك. + + + +## 3. التعليقات + +أي كود مع تعليقات جيدة هو كود ذو أهمية عُظمى. خُد وقتك لتشرح مُكوِنات كودك، كيف يعملوا، حدودهم و قدراتهم، و كيف تم ‎إنشا‎ئهم. لاتترك الأخرين في فريقك يتحزرون ماهو الهدف من هذا الكود الغامض و الغير واضح. + +تنسيق التعليق يجب أن يكون بسيط و ثابت في جميع كودك/أكوادك. + +* ضَع التعليقات على سطر جديد فوق موضوعهم/الكود الذي يقوموا بشرحه. +* أبقي طول الخط خاصتهم إلى حد معقول. على سبيل المثال: ٨٠ عمود. +* أستعمل التعليقات بحرية لتقسم كود ال"CSS" إلى أقسام منفصلة. +* أستخدم التعليقات ب"حالة الجملة النصية‎" (أبقي تعليقاتك كجُمل) و حافظ على مسافات بيضاء متناسقة. + +مثال: + +```css +/* ========================================================================== + قسم تعليق + ========================================================================== */ + +/* قسم تعليق فرعي + ========================================================================== */ + +/* +* وصف كمثال بأستخدام تنسيق "Doxygen" للتعليقات +* +* التعليق الأول من هذا الوصف الطويل يبدأ هنا و يستمر على هذا +* السطر لمدة و في النهاية ينتهي هنا عند نهاية هذه الجملة +* +* الوصف الطويل هو مناسب للشرح بالتفصيل و لتوثيق +* الكود. على سبيل المثال: ممكن أن يحتوي الشرح على "HTML"، +* رواب‎ط أو أي معلومات أخرى قد يُرى ‎أنها مهمة أو مفيدة +* +* "tag@" هذا تعليق مُسمى "tag" +* +* قا‎ئمة المهام: هذه قا‎ئمة مهام (TODO‎) تشرح هدف ما يجب تنفيذه لاحقاً. تلتف +* هذه القائمة إلى سطر جديد بعد حوالي ٨٠ حرفاً وهذه الخطو‎ط أستخدمت +* تنسيق مسافتين عند التعامل مع المسافات البيضاء. + */ + +/* تعليق بسيط من عدة كلمات */ +``` + + + +## 4. الصيغة و البنية + +الصيغة المختارة لكتابة الكود خاصتك يجب أن تضمن أن كودك: سهل القراءة؛ يقبل إضافة +التعليقات بسهولة؛ يقلل من فرص أضافة ‎أخطاء ‎غير معتمدة؛ و يجب أن تؤدي بنا الى +إمكانية مقارنة نسخ مختلفة من الكود ببعضها بسهولة. + +* أستخدم مُحدد CSS" (selector)" واحد بالسطر الواحد عندما يكون لديك عدة مُحددات في قاعدة واحدة. +* أضف مسافة واحدة قبل و بعد القوس المجعد ( { } ) الخاص بالقواعد التي تريد كتابتها. +* ألتزم بقاعدة واحد بالسطر الواحد عندما يكون لديك كتلة من القواعد. +* أستخدم مستوى واحد من التنسيق/المسافات البيضاء لكل قواعدك. +* أ‎ضف مسافة واحدة بعد كل فاصلة منقوطة ( ; ) لكل قاعدة تقوم بكتابتها +* أستخدم الأحرف الصغيرة و الأختصارات مع ألوان "hex". مثال: `#aaa` +* أستخدم علامات أقتباس مزدوجة أو مفردة بطريقة ثابتة. الأفضلية لأستخدام + علامات مزدو‎جة. مثال: `content: ""` +* أضف علامات الأقتباس لمحددات القيم. مثال: `input[type="checkbox"]`. +* _كل ما أستطعت_، تفادى أ‎ضافة نوع القيمة عندما تكون القيمة صفر. مثال: `margin: 0`. +* أضف مسافة بعد كل فاصلة في المحددات/القواعد التي تشمل عدة محددات/قيم متتالية. +* أضف فاصلة منقوطة عند نهاية القاعدة الأخيرة داخل كل كتلة قواعد. +* أحرص على أن يكون القوس المجعد المُغلق على نفس العمود الذي عليه أول حرف من كتلة القواعد. +* أفصل كل كتلة قواعد بسطر فارغ. + +مثال يشرح كل ما سبق: +
+ +```css +.selector-1, +.selector-2, +.selector-3[type="text"] { + -webkit-box-sizing: border-box; + -moz-box-sizing: border-box; + box-sizing: border-box; + display: block; + font-family: helvetica, arial, sans-serif; + color: #333; + background: #fff; + background: linear-gradient(#fff, rgba(0, 0, 0, 0.8)); +} + +.selector-a, +.selector-b { + padding: 10px; +} +``` +
+ +### ترتيب القواعد + +‎إذا أُريد من القواعد أن تكون متناسقة و ثابتة، فإذاً يجب ترتيبها من خلال نُسق +واحد بسيط. + +فرق صغيرة قد تفضل أن تجمع/تعلن عن خواص متشابهة في قواعدها بعد بعضها البعض. + مثال: التموضع "positioning" و نموذج عمل الصندوق "box-model". + +
+ +```css +.selector { + /* Positioning */ + /*التموضع*/ + position: absolute; + z-index: 10; + top: 0; + right: 0; + bottom: 0; + left: 0; + + /* Display & Box Model */ + /*طريقة العرض و نموذج الصندوق*/ + display: inline-block; + overflow: hidden; + box-sizing: border-box; + width: 100px; + height: 100px; + padding: 10px; + border: 10px solid #333; + margin: 10px; + + /* Other */ + /*أُخرى*/ + background: #000; + color: #fff; + font-family: sans-serif; + font-size: 16px; + text-align: right; +} +``` +
+ +### الأستثنائات و الأنحرافات الصغيرة عن النُسق. + +الكُتل الكبيرة من القواعد المفردة بإمكانها أستخدام سطر واحد مخلتف قليلاً. +في هذه الحالة، مسافة واحدة يجب أضافتها بعد قوس الفتح و الإغلاق الخاص بها. + +
+ +```css +.selector { + background-image: + linear-gradient(#fff, #ccc), + linear-gradient(#f3c, #4ec); + box-shadow: + 1px 1px 1px #000, + 2px 2px 1px 1px #ccc inset; +} +``` +
+ +### معالجات CSS: نُسق إضافية ينبغي أخذها بعين الأعتبار + +معالجات مُخلتفة تستخدم مزايا مُخلتفة، وظا‎ئف (Functions)، تركيب جملة ("Syntax"). أتفاقك و طريقة معاملتك لها +تنبغي أن تكون مرنة و قابلة للتمدد لتغطي الوظا‎ئف و الأمور الفريدة التي تجلبها هذه المعالجات معها. +الدليل التالي يستخدم "Sass" كمثال. + +* حد من مستويات التعشيش ("Nesting") إلى مستوى واحد و راجع + أي تعشيش يمتد على أكثر من مرحلتين. + هذا يمنع أي + محددات "CSS" مبالغة في الدقة. +* تفادى الأعداد الكبير‎ة من القواعد المُعششة. + توقف عن التعشيش عندما تصبح القراءة صعبة. + و يفضل التوقف عن التعشيش عندما سيتجاوز ال٢٠ سطر. +* دائماً أ‎ضف `تصريح` `@extend` في بداية + سطر كُل كتلة من القواعد. +* عندما يمكن، أجمع `تصريح` `@include` في أعلى + كتلة القواعد، بعد أي `تصريح` `@extend`، +* خذ بعين الأعتبار أضافة باد‎ئة `x-` لأي وظيفة + مصنوع بطريقة مخصصة (Custom functions) أو أي بادئة أخرى ذات معنى. + هذا يساعد على تفادي أي إرباك بأن و‎ظيفتك ‎الخاصة هي و‎ظيفة "CSS" فطرية + أو لتفادي تعارض عملها بسبب وجود وظيفة أخرى بنفس الأسم من مكتبة ما. + + +
+ +```scss +.selector-1 { + @extend .other-rule; + @include clearfix(); + @include box-sizing(border-box); + width: x-grid-unit(1); + // other declarations +} +``` +
+## 5. مثال عملي + +مثال يغطي عدة سيناريوهات من أنواع التنسيق +
+ + ```css +/* ========================================================================== + Grid layout + عند أستخدام نظام الشبكة + ========================================================================== */ + +/* + * Column layout with horizontal scroll. + * + * This creates a single row of full-height, non-wrapping columns that can + * be browsed horizontally within their parent. + * + * Example HTML: + * + *
+ *
+ *
+ *
+ *
+ */ + +/* + * Grid container + * + * Must only contain `.cell` children. + * + * 1. Remove inter-cell whitespace + * 2. Prevent inline-block cells wrapping + */ + +.grid { + height: 100%; + font-size: 0; /* 1 */ + white-space: nowrap; /* 2 */ +} + +/* + * Grid cells + * + * No explicit width by default. Extend with `.cell-n` classes. + * + * 1. Set the inter-cell spacing + * 2. Reset white-space inherited from `.grid` + * 3. Reset font-size inherited from `.grid` + */ + +.cell { + position: relative; + display: inline-block; + overflow: hidden; + box-sizing: border-box; + height: 100%; + padding: 0 10px; /* 1 */ + border: 2px solid #333; + vertical-align: top; + white-space: normal; /* 2 */ + font-size: 16px; /* 3 */ +} + +/* Cell states */ + +.cell.is-animating { + background-color: #fffdec; +} + +/* Cell dimensions + أبعاد الخانة + ========================================================================== */ + +.cell-1 { width: 10%; } +.cell-2 { width: 20%; } +.cell-3 { width: 30%; } +.cell-4 { width: 40%; } +.cell-5 { width: 50%; } + +/* Cell modifiers + مُعدلات الخانة + ========================================================================== */ + +.cell--detail, +.cell--important { + border-width: 4px; +} +``` +
+ + +## شكر و تقدير + +شكراً لكل من شارك في توفير التر‎جمات و لكل من شارك و عمل على [idiomatic.js](https://github.com/rwldrn/idiomatic.js). +هذا كان مصدر إلهام، أقتباس و قواعد ‎إرشادية لنا. + + +الترخيص + +_مبادئ كتابة CSS متناسق و إصطلاحي_ هو عمل Nicolas Gallagher و هو +عمل مرخص تحت تحت رخصة [Creative Commons Attribution 3.0 Unported +License](http://creativecommons.org/licenses/by/3.0/). و هذا +ينطبق على جميع المستندات و الترجمات في هذا المكان (Repository). + +مقتبس عن [github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css). + +
From 09109129fa36a434636f3aafe4186a677fdef29a Mon Sep 17 00:00:00 2001 From: Yusuf Sabbag Date: Sat, 5 Jun 2021 21:05:05 +0300 Subject: [PATCH 5/5] added the right link to the translation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 63298b1..770e118 100644 --- a/README.md +++ b/README.md @@ -339,7 +339,7 @@ An example of various conventions. ## Translations -* [العربية/Arabic](https://github.com/Yuniac/idiomatic-css/tree/master/translations/ar-AR) +* [العربية/Arabic](https://github.com/necolas/idiomatic-css/tree/master/translations/ar-AR) * [Bahasa Indonesia](https://github.com/necolas/idiomatic-css/tree/master/translations/id-ID) * [Bulgarian](https://github.com/vestimir/idiomatic-css) * [Česky](https://github.com/necolas/idiomatic-css/tree/master/translations/cs-CZ)